render.h File Reference

#include <vgl/base.h>
#include <vgl/context.h>

Go to the source code of this file.

Classes
struct	vgl_star
struct	vgl_tile_id
struct	vgl_index_list_data
struct	vgl_mesh_data
struct	vgl_texture_data
struct	vgl_draw_layer
struct	vgl_draw_item
struct	vgl_frame_begin_info

Macros
#define	VGL_TERRAIN_VERTEX_SIZE   24
#define	VGL_TERRAIN_VERTEX_POSITION_OFFSET   0
#define	VGL_TERRAIN_VERTEX_HEIGHT_OFFSET   12
#define	VGL_TERRAIN_VERTEX_UV_OFFSET   16
#define	VGL_TERRAIN_VERTEX_NORMAL_OFFSET   20
#define	VGL_TERRAIN_SAMPLE_SIZE   8
#define	VGL_TERRAIN_SAMPLE_HEIGHT_OFFSET   0
#define	VGL_TERRAIN_SAMPLE_NORMAL_OFFSET   4
#define	VGL_LOGARITHMIC_DEPTH_FAR_DEFAULT   1.0e8
#define	VGL_UPLOAD_BUDGET_DEFAULT   (16ull * 1024 * 1024)
#define	VGL_CONTOUR_INTERVAL_DEFAULT   500.0
#define	VGL_CLOUD_HEIGHT_DEFAULT   6000.0
#define	VGL_STAR_COUNT_MAX   400000u
#define	VGL_CLOUD_IMAGE_SIZE_MIN   2u
#define	VGL_CLOUD_IMAGE_WIDTH_MAX   16384u
#define	VGL_CLOUD_IMAGE_HEIGHT_MAX   8192u

Typedefs
typedef struct vgl_frame	vgl_frame
typedef uint32_t	vgl_draw_features
typedef uint32_t	vgl_debug_views

Enumerations
enum	vgl_texture_format {   VGL_TEXTURE_FORMAT_RGBA8 = 1 , VGL_TEXTURE_FORMAT_RGBA8_SRGB = 2 , VGL_TEXTURE_FORMAT_BC1 = 3 , VGL_TEXTURE_FORMAT_BC7 = 4 ,   VGL_TEXTURE_FORMAT_ETC2_RGB8 = 5 , VGL_TEXTURE_FORMAT_ASTC_4X4 = 6 , VGL_TEXTURE_FORMAT_MAX_ENUM = 0x7FFFFFFF }
enum	vgl_depth_convention { VGL_DEPTH_CONVENTION_LOGARITHMIC = 0 , VGL_DEPTH_CONVENTION_REVERSED_Z = 1 , VGL_DEPTH_CONVENTION_CONVENTIONAL = 2 , VGL_DEPTH_CONVENTION_MAX_ENUM = 0x7FFFFFFF }
enum	vgl_draw_feature {   VGL_DRAW_FEATURE_SEA_SURFACE = 0x1 , VGL_DRAW_FEATURE_ATMOSPHERE = 0x2 , VGL_DRAW_FEATURE_STARS = 0x4 , VGL_DRAW_FEATURE_CLOUDS = 0x8 ,   VGL_DRAW_FEATURE_CONTOURS = 0x10 , VGL_DRAW_FEATURE_MAX_ENUM = 0x7FFFFFFF }
enum	vgl_debug_view {   VGL_DEBUG_VIEW_WIREFRAME = 0x1 , VGL_DEBUG_VIEW_LEVEL_COLORS = 0x2 , VGL_DEBUG_VIEW_IMAGERY_SOURCE = 0x4 , VGL_DEBUG_VIEW_HEIGHT_COLORS = 0x8 ,   VGL_DEBUG_VIEW_MAX_ENUM = 0x7FFFFFFF }

Functions
vgl_result	vgl_context_texture_formats_set (vgl_context *context, const vgl_texture_format *formats, uint32_t format_count)
vgl_result	vgl_context_frame_begin (vgl_context *context, const vgl_frame_begin_info *info, vgl_frame **out_frame)
vgl_result	vgl_frame_destroys_get (const vgl_frame *frame, const uint64_t **out_resources, uint32_t *out_count)
vgl_result	vgl_frame_index_lists_get (const vgl_frame *frame, const vgl_index_list_data **out_index_lists, uint32_t *out_count)
vgl_result	vgl_frame_meshes_get (const vgl_frame *frame, const vgl_mesh_data **out_meshes, uint32_t *out_count)
vgl_result	vgl_frame_textures_get (const vgl_frame *frame, const vgl_texture_data **out_textures, uint32_t *out_count)
vgl_result	vgl_frame_draw_list_get (const vgl_frame *frame, const vgl_draw_item **out_items, uint32_t *out_count)
vgl_result	vgl_frame_draw_layers_get (const vgl_frame *frame, const vgl_draw_layer **out_layers, uint32_t *out_count)
vgl_result	vgl_frame_resource_handle_set (vgl_frame *frame, uint64_t resource, uint64_t handle)
vgl_result	vgl_frame_resource_failed (vgl_frame *frame, uint64_t resource, vgl_result reason)
vgl_result	vgl_frame_end (vgl_frame *frame)
vgl_result	vgl_context_resources_reset (vgl_context *context)

Macro Definition Documentation

VGL_TERRAIN_VERTEX_SIZE

#define VGL_TERRAIN_VERTEX_SIZE   24

Terrain vertices: VGL_TERRAIN_VERTEX_SIZE bytes each, with these attributes at these offsets. The layout is fixed for the major version.

VGL_TERRAIN_VERTEX_POSITION_OFFSET

#define VGL_TERRAIN_VERTEX_POSITION_OFFSET   0

Position relative to the mesh's centre, along the ECEF axes: 3 x float.

VGL_TERRAIN_VERTEX_HEIGHT_OFFSET

#define VGL_TERRAIN_VERTEX_HEIGHT_OFFSET   12

Height above the ellipsoid: float.

VGL_TERRAIN_VERTEX_UV_OFFSET

#define VGL_TERRAIN_VERTEX_UV_OFFSET   16

Texture coordinates over the tile, u east and v south: 2 x unsigned 16-bit normalized.

VGL_TERRAIN_VERTEX_NORMAL_OFFSET

#define VGL_TERRAIN_VERTEX_NORMAL_OFFSET   20

Normal in octahedral encoding: 2 x signed 16-bit normalized.

VGL_TERRAIN_SAMPLE_SIZE

#define VGL_TERRAIN_SAMPLE_SIZE   8

Terrain samples: VGL_TERRAIN_SAMPLE_SIZE bytes each, with these fields at these offsets. A mesh's samples are the surface it was built from, at full resolution where its grid is coarser, for shading. The layout is fixed for the major version.

VGL_TERRAIN_SAMPLE_HEIGHT_OFFSET

#define VGL_TERRAIN_SAMPLE_HEIGHT_OFFSET   0

Height above the ellipsoid: float.

VGL_TERRAIN_SAMPLE_NORMAL_OFFSET

#define VGL_TERRAIN_SAMPLE_NORMAL_OFFSET   4

Normal in octahedral encoding: 2 x signed 16-bit normalized.

VGL_LOGARITHMIC_DEPTH_FAR_DEFAULT

#define VGL_LOGARITHMIC_DEPTH_FAR_DEFAULT   1.0e8

The far distance of the logarithmic convention when the host sets none, in metres.

VGL_UPLOAD_BUDGET_DEFAULT

#define VGL_UPLOAD_BUDGET_DEFAULT   (16ull * 1024 * 1024)

Bytes of resources a frame may create when the consumer gives no upload budget.

VGL_CONTOUR_INTERVAL_DEFAULT

#define VGL_CONTOUR_INTERVAL_DEFAULT   500.0

Height between contour lines when a draw gives none, in metres.

VGL_CLOUD_HEIGHT_DEFAULT

#define VGL_CLOUD_HEIGHT_DEFAULT   6000.0

The cloud shell's height above the ellipsoid when a draw gives none, in metres: low and middle clouds.

VGL_STAR_COUNT_MAX

#define VGL_STAR_COUNT_MAX   400000u

The most stars a backend takes, which keeps its vertex buffer under 100 MiB.

VGL_CLOUD_IMAGE_SIZE_MIN

#define VGL_CLOUD_IMAGE_SIZE_MIN   2u

Limits of a cloud coverage image, in pixels, which every backend's textures take.

VGL_CLOUD_IMAGE_WIDTH_MAX

#define VGL_CLOUD_IMAGE_WIDTH_MAX   16384u

VGL_CLOUD_IMAGE_HEIGHT_MAX

#define VGL_CLOUD_IMAGE_HEIGHT_MAX   8192u

Typedef Documentation

vgl_frame

typedef struct vgl_frame vgl_frame

vgl_draw_features

typedef uint32_t vgl_draw_features

What a backend draws besides the terrain and its imagery: a combination of vgl_draw_feature values in each backend's draw settings (vgl_gl_draw_info.features, vgl_d3d11_draw_info.features, vgl::ogre::globe_settings::features).

vgl_debug_views

typedef uint32_t vgl_debug_views

Views for inspecting level of detail and loading: a combination of vgl_debug_view values in each backend's draw settings. 0 draws normally.

Enumeration Type Documentation

vgl_texture_format

enum vgl_texture_format

Enumerator
VGL_TEXTURE_FORMAT_RGBA8	Always supported.
VGL_TEXTURE_FORMAT_RGBA8_SRGB
VGL_TEXTURE_FORMAT_BC1
VGL_TEXTURE_FORMAT_BC7
VGL_TEXTURE_FORMAT_ETC2_RGB8
VGL_TEXTURE_FORMAT_ASTC_4X4
VGL_TEXTURE_FORMAT_MAX_ENUM

vgl_depth_convention

enum vgl_depth_convention

How the globe's depth is written and compared. The host owns the depth buffer and the projection, and chooses the convention when it creates a backend; geometry it draws with the globe uses the same one, so that the two depth-test against each other.

Enumerator
VGL_DEPTH_CONVENTION_LOGARITHMIC	The default, and available everywhere. The shaders write log2(1 + w) / log2(1 + far) as window depth, for the camera distance w and the far distance given when drawing (VGL_LOGARITHMIC_DEPTH_FAR_DEFAULT unless set), so the projection's near and far planes do not matter. Depth is compared with LESS and cleared to 1.
VGL_DEPTH_CONVENTION_REVERSED_Z	The host's projection maps the near plane to 1 and the far plane (ideally at infinity) to 0, in a depth range from 0 to 1. Depth is compared with GREATER and cleared to 0, ideally in a 32-bit floating-point buffer. OpenGL needs clip control for it.
VGL_DEPTH_CONVENTION_CONVENTIONAL	The host's projection as it is, compared with LESS. Small scenes only: at planetary scale, distant terrain z-fights.
VGL_DEPTH_CONVENTION_MAX_ENUM

vgl_draw_feature

enum vgl_draw_feature

Enumerator
VGL_DRAW_FEATURE_SEA_SURFACE	A sea surface: terrain below mean sea level is raised to it and shaded as water, for applications that want a flat sea rather than the ocean floor. It needs a geoid pack (vgl_draw_item.has_geoid); without one, mean sea level is the ellipsoid.
VGL_DRAW_FEATURE_ATMOSPHERE	The atmosphere (design document, section 7.6): the sky, the glow around the globe seen from space, and the haze between the camera and the terrain, lit by the sun (the draw's sun direction, or straight above the camera when that is zero), which then also reddens and dims the sunlight on the terrain and leaves the night side dark. The sky is drawn where nothing was drawn before it, at the far depth: blended over what the render target holds there, which shows through where the sky is thin, as in space.
VGL_DRAW_FEATURE_STARS	The stars set with the backend's stars_set, behind the sky: where nothing was drawn before them, at the far depth, added to what the render target holds there. With the atmosphere they fade where the sky is bright, as by day. Each is drawn as a small quad of two triangles, not as a point.
VGL_DRAW_FEATURE_CLOUDS	With the atmosphere, the clouds set with the backend's clouds_set: a shell at the draw's cloud height above the ellipsoid, over the terrain and in the sky, lit by the sun, which they shade the terrain from. They fade out as the camera comes down to the shell from above, where it would fill the view.
VGL_DRAW_FEATURE_CONTOURS	Contour lines every contour interval metres above mean sea level, every fifth one heavier. Without a geoid pack, heights are above the ellipsoid, which differs from mean sea level by up to about 100 m.
VGL_DRAW_FEATURE_MAX_ENUM

vgl_debug_view

enum vgl_debug_view

Enumerator
VGL_DEBUG_VIEW_WIREFRAME	The mesh's grid cells as bright cyan lines a pixel wide over the shading, without the diagonals that split them into triangles. Where cells are closer than four pixels, every second, fourth, eighth line and so on, which keeps them that far apart. The tiles' boundaries are always drawn, in yellow and about two pixels wide.
VGL_DEBUG_VIEW_LEVEL_COLORS	Each tile tinted by its level, with its borders outlined.
VGL_DEBUG_VIEW_IMAGERY_SOURCE	Tiles drawn with imagery coarser than themselves tinted orange, more strongly the more levels coarser it is, and tiles without imagery magenta.
VGL_DEBUG_VIEW_HEIGHT_COLORS	Colours by height above mean sea level, from the deep ocean floor to snow, instead of the imagery.
VGL_DEBUG_VIEW_MAX_ENUM

Function Documentation

vgl_context_texture_formats_set()

vgl_result vgl_context_texture_formats_set	(	vgl_context *	context,
		const vgl_texture_format *	formats,
		uint32_t	format_count
	)

States which texture formats the consumer can sample. RGBA8 is always assumed. Call it when the backend is created; until then, textures are RGBA8. A later call replaces the list, for the textures created after it; those created before keep their format. Repeats are ignored.

Parameters

context	The context.
formats	The formats, most preferred first. May be null if format_count is 0.
format_count	Number of formats.

Return values

VGL_RESULT_SUCCESS	The formats were set.
VGL_RESULT_INVALID_ARGUMENT	context is null, formats is null with a non-zero count, or a format is unknown.

Thread safety

Context-synchronized.

vgl_context_frame_begin()

vgl_result vgl_context_frame_begin	(	vgl_context *	context,
		const vgl_frame_begin_info *	info,
		vgl_frame **	out_frame
	)

Begins a frame: decides what to destroy, create and draw. Apply the lists in this order: destroy, index lists, meshes, textures; then draw. Without a view, the frame draws nothing, but still destroys what is no longer needed.

Parameters

context	The context.
info	Optional. Null selects the defaults.
out_frame	Receives the frame, valid until vgl_frame_end.

Return values

VGL_RESULT_SUCCESS	The frame began.
VGL_RESULT_INVALID_ARGUMENT	context or out_frame is null, or info is invalid.
VGL_RESULT_INVALID_OPERATION	A frame of the context is already open.
VGL_RESULT_NOT_SUPPORTED	info has fields from a newer version set.
VGL_RESULT_OUT_OF_MEMORY	The frame's lists could not grow. They do not grow once they have reached the size of the view.

Thread safety

Render thread. Must not overlap with vgl_context_update.

vgl_frame_destroys_get()

vgl_result vgl_frame_destroys_get	(	const vgl_frame *	frame,
		const uint64_t **	out_resources,
		uint32_t *	out_count
	)

Gets the resources to destroy, which come first: a view into library memory, valid until vgl_frame_end.

Parameters

frame	The frame.
out_resources	Receives the address of the first element.
out_count	Receives the number of elements; 0 for an empty list.

Return values

VGL_RESULT_SUCCESS	The list was written.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null.

Thread safety

Render thread.

vgl_frame_index_lists_get()

vgl_result vgl_frame_index_lists_get	(	const vgl_frame *	frame,
		const vgl_index_list_data **	out_index_lists,
		uint32_t *	out_count
	)

Gets the index lists to create: a view into library memory, valid until vgl_frame_end. Elements are index_list_data_size bytes apart (vgl_frame_begin_info).

Parameters

frame	The frame.
out_index_lists	Receives the address of the first element.
out_count	Receives the number of elements; 0 for an empty list.

Return values

VGL_RESULT_SUCCESS	The list was written.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null.

Thread safety

Render thread.

vgl_frame_meshes_get()

vgl_result vgl_frame_meshes_get	(	const vgl_frame *	frame,
		const vgl_mesh_data **	out_meshes,
		uint32_t *	out_count
	)

Gets the meshes to create: a view into library memory, valid until vgl_frame_end. Elements are mesh_data_size bytes apart (vgl_frame_begin_info).

Parameters

frame	The frame.
out_meshes	Receives the address of the first element.
out_count	Receives the number of elements; 0 for an empty list.

Return values

VGL_RESULT_SUCCESS	The list was written.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null.

Thread safety

Render thread.

vgl_frame_textures_get()

vgl_result vgl_frame_textures_get	(	const vgl_frame *	frame,
		const vgl_texture_data **	out_textures,
		uint32_t *	out_count
	)

Gets the textures to create: a view into library memory, valid until vgl_frame_end. Elements are texture_data_size bytes apart (vgl_frame_begin_info).

Parameters

frame	The frame.
out_textures	Receives the address of the first element.
out_count	Receives the number of elements; 0 for an empty list.

Return values

VGL_RESULT_SUCCESS	The list was written.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null.

Thread safety

Render thread.

vgl_frame_draw_list_get()

vgl_result vgl_frame_draw_list_get	(	const vgl_frame *	frame,
		const vgl_draw_item **	out_items,
		uint32_t *	out_count
	)

Gets the tiles to draw, nearest first: a view into library memory, valid until vgl_frame_end. Elements are draw_item_size bytes apart (vgl_frame_begin_info). Read it after applying the frame's creates: items may draw resources created in this frame, and carry the handles set for them. Skip an item whose mesh or index list could not be created.

Parameters

frame	The frame.
out_items	Receives the address of the first element.
out_count	Receives the number of elements; 0 for an empty list.

Return values

VGL_RESULT_SUCCESS	The list was written.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null.

Thread safety

Render thread.

vgl_frame_draw_layers_get()

vgl_result vgl_frame_draw_layers_get	(	const vgl_frame *	frame,
		const vgl_draw_layer **	out_layers,
		uint32_t *	out_count
	)

Gets the imagery layers that draw items refer to: a view into library memory, valid until vgl_frame_end. Elements are draw_layer_size bytes apart (vgl_frame_begin_info); a draw item's layers are layer_count of them from first_layer.

Parameters

frame	The frame.
out_layers	Receives the address of the first element.
out_count	Receives the number of elements; 0 for an empty list.

Return values

VGL_RESULT_SUCCESS	The list was written.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null.

Thread safety

Render thread.

vgl_frame_resource_handle_set()

vgl_result vgl_frame_resource_handle_set	(	vgl_frame *	frame,
		uint64_t	resource,
		uint64_t	handle
	)

Sets a handle that later draw items carry for a resource, such as a pointer to the consumer's own buffer object. Optional.

Parameters

frame	The frame.
resource	The resource, offered in this frame or an earlier one.
handle	The handle; any value, which the library only passes on.

Return values

VGL_RESULT_SUCCESS	The handle was set.
VGL_RESULT_INVALID_ARGUMENT	frame is null.
VGL_RESULT_NOT_FOUND	The resource does not exist, or is destroyed in this frame.

Thread safety

Render thread.

vgl_frame_resource_failed()

vgl_result vgl_frame_resource_failed	(	vgl_frame *	frame,
		uint64_t	resource,
		vgl_result	reason
	)

Reports that the consumer could not create a resource offered in this frame, for example for lack of GPU memory. It is offered again in a later frame, and is not drawn until then.

Parameters

frame	The frame.
resource	The resource offered in this frame.
reason	Why it could not be created: an error, such as VGL_RESULT_OUT_OF_MEMORY.

Return values

VGL_RESULT_SUCCESS	The failure was recorded.
VGL_RESULT_INVALID_ARGUMENT	frame is null, or reason is not an error.
VGL_RESULT_NOT_FOUND	The resource was not offered in this frame.

Thread safety

Render thread.

vgl_frame_end()

vgl_result vgl_frame_end

(

vgl_frame *

frame

)

Ends a frame. Every resource offered in it, and not reported as failed, counts as created; the CPU copies of meshes are freed.

Parameters

frame

The frame, or null.

Return values

VGL_RESULT_SUCCESS

Always.

Thread safety

Render thread.

vgl_context_resources_reset()

vgl_result vgl_context_resources_reset

(

vgl_context *

context

)

Forgets every resource, because the consumer has lost them all, for example with its graphics device. They are rebuilt and offered again as create events in later frames. Destroying a context does not destroy the consumer's resources either; the consumer frees its own objects.

Parameters

context

The context.

Return values

VGL_RESULT_SUCCESS	The resources were forgotten.
VGL_RESULT_INVALID_ARGUMENT	context is null.
VGL_RESULT_INVALID_OPERATION	A frame is open.

Thread safety

Render thread.