Renderers

This section describes the use of high-level, cross-API renderer objects.

Types

Objects

typedef struct TL_Renderer_t TL_Renderer_t

A structure to represent a graphics API renderer.

This opaque structure provides a representation of a certain graphics API.

See also

TL_RendererCreate()

See also

TL_RendererDestroy()

See also

TL_RendererDescriptor_t

See also

TL_RendererFeatures_t

Descriptors

struct TL_RendererDescriptor_t

A structure describing a renderer object to be created.

This structure describes a renderer object to be created.

Public Members

TL_RendererAPIFlags_t api

Renderer API enumeration (must not be bitwise-OR’d - only one API is supported per renderer)

TL_Version_t api_version

Renderer API version.

TL_RendererFeatures_t requirements

Renderer features to require.

void *renderer_system_descriptor

NULL or an optional descriptor for the API-specific renderer system to be created within the renderer. For example, to specify API-specific options to a Vulkan renderer, pass to this parameter a pointer to a TLVK_RendererSystemDescriptor_t struct.

Enums

enum TL_RendererAPIFlags_t

Enumeration containing graphics APIs for renderers.

This enumeration contains all graphics APIs for renderers. Not all enumerations will necessarily be accepted by renderers on creation; ensure that the appropriate module or modules were added to the build process when compiling the Thallium library.

See also

TL_Renderer_t

See also

TL_RendererDescriptor_t

Values:

enumerator TL_RENDERER_API_VULKAN_BIT = 0x10

Vulkan GPU API

enumerator TL_RENDERER_API_NULL_BIT = 0x00

Null API. Not to be used in valid Thallium applications.

Functions

uint32_t TL_RendererCreate(TL_Context_t *const context, const uint32_t count, const TL_RendererDescriptor_t *const descriptors, TL_Renderer_t **const *const renderers, const TL_Debugger_t *const debugger)

Create count renderer(s) in the given Thallium context.

This function creates count renderers into the context object context. These renderers are configured using the array of descriptors given in descriptors (the length of which is also assumed to be count).

The resultant array of renderers are allocated and output into renderers.

The count parameter must be 1 or greater. Ensure that both arrays are the same length. The index of each descriptor in the descriptors array corresponds to the index of each renderer pointer in the renderers array.

Neither descriptors or renderers can be NULL!

Note

This function can only be called once per context object! If invoked multiple times, the function will return count.

Warning

When loading the appropriate API(s), the highest version specified in the created renderer(s) is loaded. Therefore, if you are using multiple renderers over the same graphics API, only functions from the highest specified version of that API is loaded.

Parameters:

  • context – The Thallium context to create the renderers in.

  • count – Length of both descriptors and renderers arrays.

  • descriptors – Array of descriptors for created renderers.

  • renderers – Array of renderer pointers.

  • debugger – NULL or a debugger for function debugging

Returns:

The amount of renderers that were successfully created

void TL_RendererDestroy(TL_Renderer_t *const renderer)

Free the given renderer object.

This function frees the specified renderer object.

Parameters:

  • renderer – Pointer to the renderer object to free.

Renderer features

struct TL_RendererFeatures_t

A structure to hold flags for the features of a renderer object.

This structure allows the user to, for example, require desired Thallium-supported features from a renderer.

Requiring the features that will be used throughout the program at renderer creation is required to access those features, as renderers are immutable for the most part.

See also

TL_Renderer_t

Public Members

bool presentation

The renderer can present images to a swapchain.

bool wide_lines

The renderer can draw line primitives with a variable line width.