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

Classes
struct	vgl_gl_backend_create_info

struct	vgl_gl_draw_info

Macros
#define	VGL_GL_API

Typedefs
typedef void(*	vgl_gl_proc) (void)

typedef vgl_gl_proc(*	vgl_gl_get_proc_address_fn) (void user_data, const char name)

typedef struct vgl_gl_backend	vgl_gl_backend

Functions
vgl_result	vgl_gl_backend_create (vgl_context context, const vgl_gl_backend_create_info info, vgl_gl_backend **out_backend)

vgl_result	vgl_gl_backend_destroy (vgl_gl_backend *backend)

vgl_result	vgl_gl_backend_draw (vgl_gl_backend backend, const vgl_gl_draw_info info)

vgl_result	vgl_gl_backend_stars_set (vgl_gl_backend backend, const vgl_star stars, uint32_t star_count)

vgl_result	vgl_gl_backend_clouds_set (vgl_gl_backend backend, const uint8_t coverage, uint32_t width, uint32_t height)

vgl_result	vgl_gl_backend_device_reset (vgl_gl_backend *backend)

Macro Definition Documentation

◆ VGL_GL_API

#define VGL_GL_API

Typedef Documentation

◆ vgl_gl_proc

typedef void(* vgl_gl_proc) (void)

An OpenGL function, as the host's loader returns it.

◆ vgl_gl_get_proc_address_fn

typedef vgl_gl_proc(* vgl_gl_get_proc_address_fn) (void *user_data, const char *name)

Returns the address of an OpenGL or OpenGL ES function of the current context, or null. It must also return the functions of OpenGL 1.x, as glfwGetProcAddress, SDL_GL_GetProcAddress and EGL 1.5's eglGetProcAddress do (wglGetProcAddress does not).

Parameters

user_data	The pointer registered with the callback.
name	The function's name, such as "glDrawElements".

Thread safety: Calling thread: inside vgl_gl_backend_create and vgl_gl_backend_device_reset.

◆ vgl_gl_backend

typedef struct vgl_gl_backend vgl_gl_backend

Function Documentation

◆ vgl_gl_backend_create()

vgl_result vgl_gl_backend_create	(	vgl_context *	context,
		const vgl_gl_backend_create_info *	info,
		vgl_gl_backend **	out_backend
	)

Creates a backend for a context, on the OpenGL context that is current. It loads the OpenGL functions, checks the version (OpenGL 3.3 or OpenGL ES 3.0, or later), compiles its shaders and tells the context which texture formats it samples. Its objects belong to the current OpenGL context, or to the group of contexts that share objects with it.

Allocations go through the context's allocator, and messages through its log. A context has at most one consumer of the render interface at a time (docs/render-interface.md).

Parameters

context	The context. It must outlive the backend.
info	Required: the loader has no default.
out_backend	Receives the backend.

Return values

VGL_RESULT_SUCCESS	The backend was created.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null, info is invalid, or the loader is missing.
VGL_RESULT_NOT_SUPPORTED	info has fields from a newer version set; or the OpenGL version is too old, a function is missing, or the depth convention needs clip control the device lacks. The log names which.
VGL_RESULT_BACKEND_ERROR	A shader failed to compile or link; the log has the driver's message.
VGL_RESULT_OUT_OF_MEMORY	Allocation failed.

Thread safety: Render thread, with the OpenGL context current.

◆ vgl_gl_backend_destroy()

vgl_result vgl_gl_backend_destroy ( vgl_gl_backend * backend )

Deletes the backend's OpenGL objects and frees it. The context forgets its render resources (vgl_context_resources_reset), so that a backend created later receives them again.

Parameters

backend The backend, or null.

Return values

VGL_RESULT_SUCCESS Always.

Thread safety: Render thread, with the backend's OpenGL context (or one sharing its objects) current, and before the context is destroyed.

◆ vgl_gl_backend_draw()

vgl_result vgl_gl_backend_draw	(	vgl_gl_backend *	backend,
		const vgl_gl_draw_info *	info
	)

Draws the globe into the current framebuffer: takes a frame from the context, applies its resources (deleting and creating OpenGL objects) and draws its tiles: up to four imagery layers per tile, blended over colours by height where imagery is missing, and lit by the normal. It does not clear the framebuffer or present. Without a view, it draws nothing.

Call it once per frame after vgl_context_update, inside the host's render pass. The host sets up the depth buffer for the backend's depth convention (vgl/render.h).

Parameters

backend	The backend.
info	Optional. Null selects all defaults.

Return values

VGL_RESULT_SUCCESS	The globe was drawn.
VGL_RESULT_INVALID_ARGUMENT	backend is null, or info is invalid: a matrix or direction element is not finite, features or debug_views has unknown bits, or earth_rotation_angle, logarithmic_far, contour_interval or cloud_height is not finite or, but for the angle, negative.
VGL_RESULT_NOT_SUPPORTED	info has fields from a newer version set.
VGL_RESULT_INVALID_OPERATION	A frame of the context is open already, or the last vgl_gl_backend_device_reset failed.
VGL_RESULT_OUT_OF_MEMORY	The frame could not be begun (vgl_context_frame_begin).

Thread safety: Render thread, with the backend's OpenGL context (or one sharing its objects) current.

◆ vgl_gl_backend_stars_set()

vgl_result vgl_gl_backend_stars_set	(	vgl_gl_backend *	backend,
		const vgl_star *	stars,
		uint32_t	star_count
	)

Sets the stars the backend draws with VGL_DRAW_FEATURE_STARS, replacing those set before; vgl ships none, so the host supplies them from a catalogue of its choice. The stars are copied, and kept to be drawn again after vgl_gl_backend_device_reset.

Parameters

backend	The backend.
stars	The stars, or null with star_count 0 to remove them.
star_count	How many, at most VGL_STAR_COUNT_MAX.

Return values

VGL_RESULT_SUCCESS	The stars were set.
VGL_RESULT_INVALID_ARGUMENT	backend is null, stars is null with a non-zero star_count, there are too many, or a star is invalid: its direction is not of unit length, a value is not finite, a colour channel is outside [0, 1], or reserved is not 0.
VGL_RESULT_OUT_OF_MEMORY	The copy could not be allocated; the stars set before stay.

Thread safety: Render thread, with the backend's OpenGL context (or one sharing its objects) current.

◆ vgl_gl_backend_clouds_set()

vgl_result vgl_gl_backend_clouds_set	(	vgl_gl_backend *	backend,
		const uint8_t *	coverage,
		uint32_t	width,
		uint32_t	height
	)

Sets the clouds the backend draws with VGL_DRAW_FEATURE_CLOUDS, replacing those set before: their coverage of the whole globe, one byte per pixel from 0 (clear) to 255 (overcast), row 0 at 90 N and column 0 at 180 W, each pixel a step of latitude and longitude, as in NASA's cloud composites. The image is copied, with its mip levels, and kept to be drawn again after vgl_gl_backend_device_reset.

Parameters

backend	The backend.
coverage	The image, width x height bytes, rows tightly packed; or null with width and height 0 to remove the clouds.
width	Pixels from west to east, from VGL_CLOUD_IMAGE_SIZE_MIN to VGL_CLOUD_IMAGE_WIDTH_MAX.
height	Pixels from north to south, from VGL_CLOUD_IMAGE_SIZE_MIN to VGL_CLOUD_IMAGE_HEIGHT_MAX.

Return values

VGL_RESULT_SUCCESS	The clouds were set.
VGL_RESULT_INVALID_ARGUMENT	backend is null, or the image is null or of a size outside the limits, but for a removal.
VGL_RESULT_OUT_OF_MEMORY	The copy could not be allocated; the clouds set before stay.

Thread safety: Render thread, with the backend's OpenGL context (or one sharing its objects) current.

◆ vgl_gl_backend_device_reset()

vgl_result vgl_gl_backend_device_reset ( vgl_gl_backend * backend )

Recovers from a lost OpenGL context, for example after an Android app returns from the background: forgets the backend's OpenGL objects without deleting them, then loads the functions and builds its shaders again on the OpenGL context that is current now. The context forgets its render resources too, and offers them again over the next frames.

Parameters

backend The backend.

Return values

VGL_RESULT_SUCCESS	The backend is ready on the new OpenGL context.
VGL_RESULT_INVALID_ARGUMENT	backend is null.
VGL_RESULT_NOT_SUPPORTED	The new OpenGL context cannot be used, as for vgl_gl_backend_create. Draws fail until a reset succeeds.
VGL_RESULT_BACKEND_ERROR	A shader failed to compile or link.

Thread safety: Render thread, with the new OpenGL context current.

Classes

Macros

Typedefs

Functions

Macro Definition Documentation

◆ VGL_GL_API

Typedef Documentation

◆ vgl_gl_proc

◆ vgl_gl_get_proc_address_fn

◆ vgl_gl_backend

Function Documentation

◆ vgl_gl_backend_create()

◆ vgl_gl_backend_destroy()

◆ vgl_gl_backend_draw()

◆ vgl_gl_backend_stars_set()

◆ vgl_gl_backend_clouds_set()

◆ vgl_gl_backend_device_reset()