d3d11.h File Reference

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

Go to the source code of this file.

Classes
struct	vgl_d3d11_backend_create_info
struct	vgl_d3d11_draw_info

Macros
#define	VGL_D3D11_API

Typedefs
typedef struct vgl_d3d11_backend	vgl_d3d11_backend

Functions
vgl_result	vgl_d3d11_backend_create (vgl_context *context, const vgl_d3d11_backend_create_info *info, vgl_d3d11_backend **out_backend)
vgl_result	vgl_d3d11_backend_destroy (vgl_d3d11_backend *backend)
vgl_result	vgl_d3d11_backend_draw (vgl_d3d11_backend *backend, const vgl_d3d11_draw_info *info)
vgl_result	vgl_d3d11_backend_clouds_set (vgl_d3d11_backend *backend, const uint8_t *coverage, uint32_t width, uint32_t height)
vgl_result	vgl_d3d11_backend_stars_set (vgl_d3d11_backend *backend, const vgl_star *stars, uint32_t star_count)
vgl_result	vgl_d3d11_backend_device_reset (vgl_d3d11_backend *backend, ID3D11Device *device, ID3D11DeviceContext *device_context)

Macro Definition Documentation

VGL_D3D11_API

#define VGL_D3D11_API

Typedef Documentation

vgl_d3d11_backend

typedef struct vgl_d3d11_backend vgl_d3d11_backend

Function Documentation

vgl_d3d11_backend_create()

vgl_result vgl_d3d11_backend_create	(	vgl_context *	context,
		const vgl_d3d11_backend_create_info *	info,
		vgl_d3d11_backend **	out_backend
	)

Creates a backend for a context on a device: checks the feature level, creates its shaders and states, and tells the context which texture formats it samples.

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 device 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 device or device context is missing.
VGL_RESULT_NOT_SUPPORTED	info has fields from a newer version set, or the device's feature level is below 11_0.
VGL_RESULT_BACKEND_ERROR	Direct3D failed to create a shader or state; the log has its HRESULT.
VGL_RESULT_OUT_OF_MEMORY	Allocation failed.

Thread safety

Render thread, on the thread that owns the device context.

vgl_d3d11_backend_destroy()

vgl_result vgl_d3d11_backend_destroy

(

vgl_d3d11_backend *

backend

)

Releases the backend's Direct3D objects and its references to the device and device context, 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, on the thread that owns the device context, before the context is destroyed.

vgl_d3d11_backend_draw()

vgl_result vgl_d3d11_backend_draw	(	vgl_d3d11_backend *	backend,
		const vgl_d3d11_draw_info *	info
	)

Draws the globe into the device context's bound render target: takes a frame from the context, applies its resources (releasing and creating Direct3D 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 or present. Without a view, it draws nothing.

Call it once per frame after vgl_context_update. The host binds a render target and a depth buffer set up for the backend's depth convention (vgl/render.h), and sets the viewport.

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_d3d11_backend_device_reset failed.
VGL_RESULT_OUT_OF_MEMORY	The frame could not be begun (vgl_context_frame_begin).

Thread safety

Render thread, on the thread that owns the device context.

vgl_d3d11_backend_clouds_set()

vgl_result vgl_d3d11_backend_clouds_set	(	vgl_d3d11_backend *	backend,
		const uint8_t *	coverage,
		uint32_t	width,
		uint32_t	height
	)

Sets the clouds the backend draws with VGL_DRAW_FEATURE_CLOUDS, as vgl_gl_backend_clouds_set describes: a coverage image of the whole globe, copied with its mip levels, and kept for vgl_d3d11_backend_device_reset.

Parameters

backend	The backend.
coverage	The image, width x height bytes, rows from the north; or null with width and height 0 to remove the clouds.
width	Pixels from west to east, from 2 to 16,384.
height	Pixels from north to south, from 2 to 8,192.

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.

vgl_d3d11_backend_stars_set()

vgl_result vgl_d3d11_backend_stars_set	(	vgl_d3d11_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, as vgl_gl_backend_stars_set does: copied, kept for vgl_d3d11_backend_device_reset, and drawn as small quads. vgl ships no stars.

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 (vgl_gl_backend_stars_set).
VGL_RESULT_OUT_OF_MEMORY	The copy could not be allocated; the stars set before stay.

Thread safety

Render thread.

vgl_d3d11_backend_device_reset()

vgl_result vgl_d3d11_backend_device_reset	(	vgl_d3d11_backend *	backend,
		ID3D11Device *	device,
		ID3D11DeviceContext *	device_context
	)

Recovers from a removed device: forgets the backend's objects of the old device without using them again, takes the new device and device context, and creates its shaders and states on them. The context forgets its render resources too, and offers them again over the next frames.

Parameters

backend	The backend.
device	The new device. The backend holds a reference.
device_context	The device context to draw with on it. The backend holds a reference.

Return values

VGL_RESULT_SUCCESS	The backend is ready on the new device.
VGL_RESULT_INVALID_ARGUMENT	A pointer is null.
VGL_RESULT_NOT_SUPPORTED	The new device's feature level is below 11_0. Draws fail until a reset succeeds.
VGL_RESULT_BACKEND_ERROR	Direct3D failed to create a shader or state.

Thread safety

Render thread, on the thread that owns the new device context.