#include <vgl/base.h>
#include <vgl/foundation.h>
#include <vgl/geodesy.h>

Classes
struct	vgl_context_create_info

struct	vgl_update_info

struct	vgl_view

struct	vgl_pack_create_info

struct	vgl_ray_hit

struct	vgl_context_statistics

Typedefs
typedef struct vgl_context	vgl_context

typedef struct vgl_pack	vgl_pack

Enumerations
enum	vgl_pack_state { VGL_PACK_STATE_LOADING = 1 , VGL_PACK_STATE_READY = 2 , VGL_PACK_STATE_FAILED = 3 , VGL_PACK_STATE_MAX_ENUM = 0x7FFFFFFF }

enum	vgl_height_reference { VGL_HEIGHT_REFERENCE_ELLIPSOID = 0 , VGL_HEIGHT_REFERENCE_MEAN_SEA_LEVEL = 1 , VGL_HEIGHT_REFERENCE_MAX_ENUM = 0x7FFFFFFF }

Functions
vgl_result	vgl_context_create (const vgl_context_create_info info, vgl_context *out_context)

vgl_result	vgl_context_destroy (vgl_context *context)

vgl_result	vgl_context_allocator_get (const vgl_context context, vgl_allocator_interface out_allocator)

vgl_result	vgl_context_log (const vgl_context context, vgl_log_level level, const char message)

vgl_result	vgl_context_view_set (vgl_context context, const vgl_view view)

vgl_result	vgl_view_project (const vgl_view view, const vgl_dvec3 position, vgl_dvec3 *out_window)

vgl_result	vgl_view_geodetic_project (const vgl_view view, const vgl_ellipsoid ellipsoid, const vgl_geodetic geodetic, vgl_dvec3 out_window)

vgl_result	vgl_context_view_get (const vgl_context context, vgl_view out_view)

vgl_result	vgl_context_update (vgl_context context, const vgl_update_info info)

vgl_result	vgl_pack_create (vgl_context context, const vgl_pack_create_info info, vgl_pack **out_pack)

vgl_result	vgl_pack_destroy (vgl_pack *pack)

vgl_result	vgl_pack_state_get (const vgl_pack pack, vgl_pack_state out_state, vgl_result *out_failure)

vgl_result	vgl_pack_priority_set (vgl_pack *pack, int32_t priority)

vgl_result	vgl_pack_priority_get (const vgl_pack pack, int32_t out_priority)

vgl_result	vgl_pack_opacity_set (vgl_pack *pack, float opacity)

vgl_result	vgl_pack_opacity_get (const vgl_pack pack, float out_opacity)

vgl_result	vgl_context_height_query (vgl_context context, double latitude, double longitude, vgl_height_reference reference, double out_height)

vgl_result	vgl_context_ray_query (vgl_context context, const vgl_dvec3 origin, const vgl_dvec3 direction, vgl_ray_hit out_hit)

vgl_result	vgl_context_attribution_get (const vgl_context context, uint32_t inout_count, const char **out_strings)

vgl_result	vgl_context_statistics_get (const vgl_context context, vgl_context_statistics out_statistics)

Typedef Documentation

◆ vgl_context

typedef struct vgl_context vgl_context

◆ vgl_pack

typedef struct vgl_pack vgl_pack

Enumeration Type Documentation

◆ vgl_pack_state

enum vgl_pack_state

What a pack is doing. 0 is never written.

Enumerator
VGL_PACK_STATE_LOADING	The manifest is being read.
VGL_PACK_STATE_READY	The pack is in use.
VGL_PACK_STATE_FAILED	The pack could not be used; see the failure result.
VGL_PACK_STATE_MAX_ENUM

◆ vgl_height_reference

enum vgl_height_reference

Enumerator
VGL_HEIGHT_REFERENCE_ELLIPSOID	Height above the reference ellipsoid.
VGL_HEIGHT_REFERENCE_MEAN_SEA_LEVEL	Height above the geoid (needs a geoid pack).
VGL_HEIGHT_REFERENCE_MAX_ENUM

Function Documentation

◆ vgl_context_create()

vgl_result vgl_context_create	(	const vgl_context_create_info *	info,
		vgl_context **	out_context
	)

Creates a context.

The interface tables are copied; their user_data pointers must stay valid until the context is destroyed, and the allocator must outlive every request and task of the context.

Parameters

info	Optional. Null selects all defaults (and no I/O).
out_context	Receives the context.

Return values

VGL_RESULT_SUCCESS	The context was created.
VGL_RESULT_INVALID_ARGUMENT	out_context is null, or info or one of its interfaces is invalid.
VGL_RESULT_NOT_SUPPORTED	info uses fields of a newer version of vgl.
VGL_RESULT_VERSION_MISMATCH	An interface has a version this vgl does not know.
VGL_RESULT_OUT_OF_MEMORY	Allocation failed.

Thread safety: Free-threaded.

◆ vgl_context_destroy()

vgl_result vgl_context_destroy ( vgl_context * context )

Destroys a context, and every pack that remains in it (with a warning for each).

Reads and tasks still outstanding are cancelled; when the host completes them later, the completions are discarded. Tasks that are running are waited for.

Parameters

context The context, or null.

Return values

VGL_RESULT_SUCCESS Always.

Thread safety: Context-synchronized.

◆ vgl_context_allocator_get()

vgl_result vgl_context_allocator_get	(	const vgl_context *	context,
		vgl_allocator_interface *	out_allocator
	)

Gets the allocator of the context: the host's, or one that uses the C heap. Libraries that work on behalf of a context, such as the backends, allocate through it, so that all of the context's memory reaches the host's allocator (NFR-03). The table stays valid while the context exists.

Parameters

context	The context.
out_allocator	Receives the allocator interface.

Return values

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

Thread safety: Free-threaded.

◆ vgl_context_log()

vgl_result vgl_context_log	(	const vgl_context *	context,
		vgl_log_level	level,
		const char *	message
	)

Passes a message to the context's log callback, if one is set and the level is enabled. Libraries that work on behalf of a context, such as the backends, log through it, so that their messages reach the host's log (docs/c-api.md, section 13).

Parameters

context	The context.
level	Severity: VGL_LOG_LEVEL_ERROR to VGL_LOG_LEVEL_DEBUG.
message	UTF-8 text without a trailing newline, starting with the name of the API function involved.

Return values

VGL_RESULT_SUCCESS	The message was passed on, or the level is disabled.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null, or level is not a message level.

Thread safety: Free-threaded. The log callback runs on the calling thread.

◆ vgl_context_view_set()

vgl_result vgl_context_view_set	(	vgl_context *	context,
		const vgl_view *	view
	)

Sets the view that vgl_context_update selects tiles for. The view is copied.

Parameters

context	The context.
view	The view, or null to stop selecting tiles.

Return values

VGL_RESULT_SUCCESS	The view was set.
VGL_RESULT_INVALID_ARGUMENT	context is null, or view is invalid: a matrix element is not finite, the view matrix is not invertible, the viewport is empty, or the error is negative.
VGL_RESULT_NOT_SUPPORTED	view has fields from a newer version set.

Thread safety: Context-synchronized.

◆ vgl_view_project()

vgl_result vgl_view_project	(	const vgl_view *	view,
		const vgl_dvec3 *	position,
		vgl_dvec3 *	out_window
	)

Projects a position to the viewport of a view: where it appears on the screen, as for a label or a marker. The view is the same as for vgl_context_view_set, and any handedness and depth mapping work. The position is ECEF; vgl_ellipsoid_geodetic_to_ecef turns a latitude, longitude and height into one. The projection is composed in double precision.

The result does not say whether the position is visible: it may lie outside the viewport, beyond the far plane, or behind the terrain or the globe. vgl_context_ray_query from the camera towards it tells whether something is in the way.

Parameters

view	The view.
position	The position, ECEF, in metres.
out_window	Receives the position in the viewport: x in pixels from its left edge, y in pixels from its top edge, downwards, so pixel (i, j) has its centre at (i + 0.5, j + 0.5); and z, the clip-space w, which a perspective projection makes the distance from the camera along the view axis, in metres. Unchanged when the position is behind the camera. OpenGL's window coordinates count y upwards: they are (x, viewport_height - y).

Return values

VGL_RESULT_SUCCESS	The position is in front of the camera: its clip-space w is positive.
VGL_RESULT_NOT_FOUND	The position is behind the camera, or on the plane through it, where it has no place on the screen.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null, the position is not finite, or the view is invalid, as for vgl_context_view_set.
VGL_RESULT_NOT_SUPPORTED	view has fields from a newer version set.

Thread safety: Free-threaded: it takes no context.

◆ vgl_view_geodetic_project()

vgl_result vgl_view_geodetic_project	(	const vgl_view *	view,
		const vgl_ellipsoid *	ellipsoid,
		const vgl_geodetic *	geodetic,
		vgl_dvec3 *	out_window
	)

Projects a geodetic position to the viewport of a view: vgl_ellipsoid_geodetic_to_ecef, then vgl_view_project, which describes the result. The height is above the ellipsoid; for a height above mean sea level, add the geoid's height there first (vgl_context_height_query gives both).

Parameters

view	The view.
ellipsoid	Optional. The reference ellipsoid; null selects WGS84.
geodetic	The position: latitude and longitude in radians, height in metres.
out_window	Receives x and y in pixels from the viewport's top left, y downwards, and the clip-space w, as for vgl_view_project. Unchanged when the position is behind the camera.

Return values

VGL_RESULT_SUCCESS	The position is in front of the camera.
VGL_RESULT_NOT_FOUND	The position is behind the camera.
VGL_RESULT_INVALID_ARGUMENT	A pointer other than ellipsoid is null, the ellipsoid or the view is invalid, or the position is not finite or its latitude is out of range.
VGL_RESULT_NOT_SUPPORTED	view has fields from a newer version set.

Thread safety: Free-threaded: it takes no context.

◆ vgl_context_view_get()

vgl_result vgl_context_view_get	(	const vgl_context *	context,
		vgl_view *	out_view
	)

Gets the view set with vgl_context_view_set, for example for a backend that needs its projection matrix.

Parameters

context	The context.
out_view	Receives the view, an output structure (docs/c-api.md, section 8.4): set its struct_size, at least 8.

Return values

VGL_RESULT_SUCCESS	The view was written.
VGL_RESULT_NOT_FOUND	No view is set; out_view is unchanged.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null, or out_view->struct_size is below 8.

Thread safety: Context-synchronized.

◆ vgl_context_update()

vgl_result vgl_context_update	(	vgl_context *	context,
		const vgl_update_info *	info
	)

Advances loading: processes completed reads and tasks, decodes (when there is no task interface) within the time budget, selects tiles for the view and requests the ones that are missing, and evicts decoded tiles beyond the CPU budget.

Parameters

context	The context.
info	Optional. Null selects the defaults.

Return values

VGL_RESULT_SUCCESS	The update ran.
VGL_RESULT_INVALID_ARGUMENT	context is null or info is invalid.
VGL_RESULT_NOT_SUPPORTED	info has fields from a newer version set.
VGL_RESULT_INVALID_OPERATION	A frame is open (docs/render-interface.md, section 9).

Thread safety: Context-synchronized.

◆ vgl_pack_create()

vgl_result vgl_pack_create	(	vgl_context *	context,
		const vgl_pack_create_info *	info,
		vgl_pack **	out_pack
	)

Adds a pack to a context, and starts reading its manifest (docs/pack-format.md). Once it is ready, an elevation pack shapes the terrain and takes part in height queries, and an imagery pack is an imagery layer, blended over the layers of lower priority. A geoid pack provides heights above mean sea level; a context takes at most one.

Parameters

context	The context.
info	The pack's location and priority.
out_pack	Receives the pack, which belongs to the context.

Return values

VGL_RESULT_SUCCESS	The pack was added and is loading.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null, or info is invalid.
VGL_RESULT_NOT_SUPPORTED	info has fields from a newer version set.
VGL_RESULT_INVALID_OPERATION	The context has no I/O interface.
VGL_RESULT_OUT_OF_MEMORY	Allocation failed.

Thread safety: Context-synchronized.

◆ vgl_pack_destroy()

vgl_result vgl_pack_destroy ( vgl_pack * pack )

Removes a pack from its context. Its outstanding reads are cancelled, and its decoded tiles are freed.

Parameters

pack	The pack, or null.

Return values

VGL_RESULT_SUCCESS Always.

Thread safety: Context-synchronized.

◆ vgl_pack_state_get()

vgl_result vgl_pack_state_get	(	const vgl_pack *	pack,
		vgl_pack_state *	out_state,
		vgl_result *	out_failure
	)

Gets the state of a pack.

Parameters

pack	The pack.
out_state	Receives the state.
out_failure	Optional. Receives why the pack failed, or VGL_RESULT_SUCCESS if it has not: for example VGL_RESULT_NOT_FOUND, VGL_RESULT_CORRUPT_DATA or VGL_RESULT_VERSION_MISMATCH. The log has the details.

Return values

VGL_RESULT_SUCCESS	The state was written.
VGL_RESULT_INVALID_ARGUMENT	pack or out_state is null.

Thread safety: Context-synchronized.

◆ vgl_pack_priority_set()

vgl_result vgl_pack_priority_set	(	vgl_pack *	pack,
		int32_t	priority
	)

Changes a pack's priority, as set in vgl_pack_create_info. Among equal priorities, the pack created later still wins. For elevation packs, the terrain is built again in the new order, and drawn in the old one until it is. For imagery packs, the layers are drawn in the new order from the next frame. Ignored for a geoid pack.

Parameters

pack	The pack.
priority	The new priority.

Return values

VGL_RESULT_SUCCESS	The priority was set.
VGL_RESULT_INVALID_ARGUMENT	pack is null.

Thread safety: Context-synchronized.

◆ vgl_pack_priority_get()

vgl_result vgl_pack_priority_get	(	const vgl_pack *	pack,
		int32_t *	out_priority
	)

Gets a pack's priority.

Parameters

pack	The pack.
out_priority	Receives the priority.

Return values

VGL_RESULT_SUCCESS	The priority was written.
VGL_RESULT_INVALID_ARGUMENT	pack or out_priority is null.

Thread safety: Context-synchronized.

◆ vgl_pack_opacity_set()

vgl_result vgl_pack_opacity_set	(	vgl_pack *	pack,
		float	opacity
	)

Sets the opacity of an imagery pack's layer: it is blended over the layers below it by its imagery's alpha times the opacity (docs/render-interface.md, section 5). At 0 the layer is hidden: its imagery is neither loaded nor drawn, and its attribution is not reported. New packs have opacity 1. Ignored for elevation and geoid packs.

Parameters

pack	The pack.
opacity	From 0 (hidden) to 1 (opaque).

Return values

VGL_RESULT_SUCCESS	The opacity was set.
VGL_RESULT_INVALID_ARGUMENT	pack is null, or opacity is not from 0 to 1.

Thread safety: Context-synchronized.

◆ vgl_pack_opacity_get()

vgl_result vgl_pack_opacity_get	(	const vgl_pack *	pack,
		float *	out_opacity
	)

Gets the opacity of a pack's layer.

Parameters

pack	The pack.
out_opacity	Receives the opacity, from 0 to 1.

Return values

VGL_RESULT_SUCCESS	The opacity was written.
VGL_RESULT_INVALID_ARGUMENT	pack or out_opacity is null.

Thread safety: Context-synchronized.

◆ vgl_context_height_query()

vgl_result vgl_context_height_query	(	vgl_context *	context,
		double	latitude,
		double	longitude,
		vgl_height_reference	reference,
		double *	out_height
	)

Queries the terrain height at a geodetic position (FR-06).

The height comes from the highest-priority elevation pack with data at the position, at the deepest level loaded so far, interpolated as docs/pack-format.md, section 6.4 describes. A query starts reading whatever finer data it needs; call vgl_context_update to receive it.

Parameters

context	The context.
latitude	Geodetic latitude in radians, in [-pi/2, pi/2].
longitude	Longitude in radians.
reference	What the height is relative to.
out_height	Receives the height in metres. Unchanged on an error.

Return values

VGL_RESULT_SUCCESS	The height is final: it comes from the finest data the packs have at the position.
VGL_RESULT_NOT_READY	Finer data, a pack's manifest, or the geoid is still loading, or a read of it could not start yet for lack of memory (logged); out_height holds the best current value, NaN while no data has loaded at all, and above the ellipsoid while the geoid has not.
VGL_RESULT_NOT_FOUND	No ready elevation pack has data at the position.
VGL_RESULT_INVALID_OPERATION	reference is VGL_HEIGHT_REFERENCE_MEAN_SEA_LEVEL, and the context has no geoid pack.
VGL_RESULT_INVALID_ARGUMENT	context or out_height is null, an angle is not finite or out of range, or reference is unknown.

Thread safety: Context-synchronized.

◆ vgl_context_ray_query()

vgl_result vgl_context_ray_query	(	vgl_context *	context,
		const vgl_dvec3 *	origin,
		const vgl_dvec3 *	direction,
		vgl_ray_hit *	out_hit
	)

Intersects a ray with the terrain (FR-07): picking. The terrain is the one height queries see, from the deepest data loaded so far, and the ellipsoid where no elevation pack has data. It may lie a little off the drawn terrain, whose tiles are coarser where they are far from the camera; under the cursor, by about the screen-space error. Ridges narrower than the finest loaded sample spacing may be missed. Like a height query, it starts reading the finer data the hit needs; call vgl_context_update to receive it, and query again.

Parameters

context	The context.
origin	The ray's origin in ECEF, in metres. It may lie anywhere, even under the terrain, which then counts as hit at distance 0.
direction	The ray's direction in ECEF; any length but 0.
out_hit	Receives the nearest hit, an output structure (docs/c-api.md, section 8.4): set its struct_size, at least 8. Unchanged when there is no hit.

Return values

VGL_RESULT_SUCCESS	The ray meets the terrain, from the finest data the packs have at the hit.
VGL_RESULT_NOT_READY	The ray meets the terrain, but finer data at the hit, or a pack's manifest, is still loading, or a read of it could not start yet for lack of memory (logged); out_hit holds the best current hit.
VGL_RESULT_NOT_FOUND	The ray misses the globe.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null, out_hit's struct_size is below 8, or origin or direction is not finite or direction is 0.

Thread safety: Context-synchronized.

◆ vgl_context_attribution_get()

vgl_result vgl_context_attribution_get	(	const vgl_context *	context,
		uint32_t *	inout_count,
		const char **	out_strings
	)

Gets the credits of the data in view (FR-08): the attribution lines of every pack whose tiles the view selects or the last frame drew, in pack priority order, each distinct line once. A geoid pack counts as in view whenever any terrain is, since it shapes every elevation tile. Hosts display them while the data is visible, as the data's licenses require. Uses the two-call pattern (docs/c-api.md, section 6.3).

Parameters

context	The context.
inout_count	In: the capacity of out_strings. Out: the number of lines written, or available if out_strings is null.
out_strings	Optional. Receives UTF-8 lines, valid until the pack they come from is destroyed.

Return values

VGL_RESULT_SUCCESS	All lines were written, or counted.
VGL_RESULT_INCOMPLETE	out_strings was too small; *inout_count lines were written.
VGL_RESULT_INVALID_ARGUMENT	context or inout_count is null.

Thread safety: Context-synchronized.

◆ vgl_context_statistics_get()

vgl_result vgl_context_statistics_get	(	const vgl_context *	context,
		vgl_context_statistics *	out_statistics
	)

Gets the statistics of a context.

Parameters

context	The context.
out_statistics	Receives the statistics, an output structure (docs/c-api.md, section 8.4): set its struct_size, at least 8.

Return values

VGL_RESULT_SUCCESS	The statistics were written.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null, or struct_size is below 8.

Thread safety: Context-synchronized.

Classes

Typedefs

Enumerations

Functions

Typedef Documentation

◆ vgl_context

◆ vgl_pack

Enumeration Type Documentation

◆ vgl_pack_state

◆ vgl_height_reference

Function Documentation

◆ vgl_context_create()

◆ vgl_context_destroy()

◆ vgl_context_allocator_get()

◆ vgl_context_log()

◆ vgl_context_view_set()

◆ vgl_view_project()

◆ vgl_view_geodetic_project()

◆ vgl_context_view_get()

◆ vgl_context_update()

◆ vgl_pack_create()

◆ vgl_pack_destroy()

◆ vgl_pack_state_get()

◆ vgl_pack_priority_set()

◆ vgl_pack_priority_get()

◆ vgl_pack_opacity_set()

◆ vgl_pack_opacity_get()

◆ vgl_context_height_query()

◆ vgl_context_ray_query()

◆ vgl_context_attribution_get()

◆ vgl_context_statistics_get()