Pipelines and Pipeline Configuration

This section describes the use of Thallium’s cross-API pipeline objects.

Types

Objects

typedef struct TL_Pipeline_t TL_Pipeline_t

A structure to represent a pipeline object.

This opaque structure represents a graphics, compute, or ray tracing pipeline object.

See also

TL_PipelineCreate()

See also

TL_PipelineDestroy()

See also

TL_PipelineDescriptor_t

Descriptors

struct TL_PipelineDescriptor_t

A structure describing a pipeline object to be created.

This structure describes a pipeline object to be created.

Public Members

TL_PipelineType_t type: The type of pipeline object to create.

TL_PrimitiveTopology_t primitive_topology: The topology to assume for assembly of primitives. If NULL, then TL_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST is used by default. This value is ignored in compute and ray tracing pipelines.

TL_PipelineRasterizerDescriptor_t rasterizer: A descriptor of the rasterization stage of the pipeline. This value is ignored in compute and ray tracing pipelines.

TL_PipelineDepthTestDescriptor_t depth_test: A descriptor of the depth-testing stage of the pipeline. This value is ignored in compute and ray tracing pipelines.

uint32_t viewport_count: The amount of viewports in the viewports array; ignored if viewports is NULL. This value is ignored in compute and ray tracing pipelines.

TL_Viewport_t *viewports: NULL or an array of viewports - if NULL, any viewports must be set dynamically instead. This value is ignored in compute and ray tracing pipelines.

uint32_t scissor_count: The amount of viewports in the viewports array; ignored if viewports is NULL. This value is ignored in compute and ray tracing pipelines.

TL_Rect2D_t *scissors: NULL or an array of scissor rectangles - if NULL, any scissors must be set dynamically instead. This value is ignored in compute and ray tracing pipelines.

struct TL_PipelineRasterizerDescriptor_t

A descriptor struct for configuration of a graphics pipeline’s rasterization stage (‘rasterizer’).

This structure describes a pipeline’s rasterization stage (‘rasterizer’).

Public Members

bool depth_clamp: If true, primitives will practically not be clipped to the near and far planes of the frustum.

bool rasterizer_discard: If true, primitives will be discarded immediately before rasterization, ending the pipeline after the vertex processing stage.

TL_PolygonMode_t polygon_mode: Polygon render mode - TL_POLYGON_MODE_FILL is assumed by default.

TL_CullModeFlags_t cull_modes: Bitmask of modes for polygon discarding a.k.a. culling. By default, no polygons are culled (TL_CULL_MODE_NONE_BIT).

bool clockwise_front_face: If true, then clockwise-winding polygons will be assumed to be front-facing. Otherwise, counter-clockwise polygons are front-facing.

bool depth_bias: If true, fragment depth values will be biased according to other depth_bias_* parameters.

float depth_bias_constant_factor: A constant value to be added to the depth of each fragment.

float depth_bias_slope_factor: A factor applied to a fragment’s slope in depth bias calculations.

float depth_bias_clamp: The maximum (or minimum) depth bias of a fragment.

float line_width: The width of all line primitives. This value is silently ignored and defaults to 1.0 if the wide_lines feature is disabled on the relevant renderer.

struct TL_PipelineDepthTestDescriptor_t

A descriptor struct for configuration of a graphics pipeline’s depth testing stage.

This structure describes a graphics pipeline’s depth testing stage.

Public Members

bool test_enabled: If true, the depth test is enabled.

bool write_enabled: If true, then writing to the depth buffer is enabled.

TL_CompareOp_t compare_op: Depth test comparison function - TL_COMPARE_OP_NEVER is the default value.

Enums

enum TL_PipelineType_t

Enumeration containing types of Thallium pipeline objects.

This enumeration contains types of Thallium pipeline objects.

See also

TL_Pipeline_t

See also

TL_PipelineDescriptor_t

Values:

enumerator TL_PIPELINE_TYPE_GRAPHICS: Represent a graphics pipeline.

enumerator TL_PIPELINE_TYPE_COMPUTE: Represent a compute pipeline (currently unimplemented and reserved for future use)

enumerator TL_PIPELINE_TYPE_RAY_TRACING: Represent a ray tracing pipeline (currently unimplemented and reserved for future use)

Functions

TL_Pipeline_t *TL_PipelineCreate(const TL_Renderer_t *const renderer, const TL_PipelineDescriptor_t descriptor)

Create and return a handle to a new Thallium pipeline object under the given renderer.

This function creates and returns a new Thallium pipeline object for use with the specified renderer.

See also

TL_Pipeline_t

Parameters:

renderer – Renderer to create the pipeline for.
descriptor – A pipeline descriptor struct.

Returns:

The new pipeline

void TL_PipelineDestroy(TL_Pipeline_t *const pipeline)

Free the given pipeline object.

This function frees the specified pipeline object.

Parameters:

pipeline – Pointer to the pipeline object to free.

Pipeline configuration options

enum TL_CompareOp_t

Enumeration of comparison operators for depth, stencil, and sampler operations.

Possible values of this enumeration represent comparison operators used in depth, stencil, and sampler operations.

Values:

enumerator TL_COMPARE_OP_NEVER: Comparison always evaluates false.

enumerator TL_COMPARE_OP_LESS: Comparison evaluates as reference < test.

enumerator TL_COMPARE_OP_EQUAL: Comparison evaluates as reference == test.

enumerator TL_COMPARE_OP_LESS_OR_EQUAL: Comparison evaluates as reference <= test.

enumerator TL_COMPARE_OP_GREATER: Comparison evaluates as reference > test.

enumerator TL_COMPARE_OP_NOT_EQUAL: Comparison evaluates as reference != test.

enumerator TL_COMPARE_OP_GREATER_OR_EQUAL: Comparison evaluates as reference >= test.

enumerator TL_COMPARE_OP_ALWAYS: Comparison always evaluates true.

enum TL_CullModeFlags_t

Enumeration of modes for polygon culling (discarding) at rasterization.

This enumeration contains modes of polygon culling/discarding during the rasterization stage of a graphics pipeline.

Values:

enumerator TL_CULL_MODE_NONE_BIT = 0x00: Do not cull polygons.

enumerator TL_CULL_MODE_FRONT_BIT = 0x01: Cull front-facing polygons.

enumerator TL_CULL_MODE_BACK_BIT = 0x02: Cull back-facing polygons.

enumerator TL_CULL_MODE_FRONT_AND_BACK_BIT = 0x03: Cull all polygons.

enum TL_PrimitiveTopology_t

Enumeration of primitive rendering topologies.

This enumeration contains supported primitive graphics topologies.

Note

Strip topology enumerators are indicated with the left-most bit set. When these options are used, a fixed vertex index value is used to restart the assembly of primitives - this value is the maximum value for the type format used by the related index buffer.

Values:

enumerator TL_PRIMITIVE_TOPOLOGY_POINT_LIST = 0x01: A series of separate point primitives.

enumerator TL_PRIMITIVE_TOPOLOGY_LINE_LIST = 0x02: A series of separate line primitives.

enumerator TL_PRIMITIVE_TOPOLOGY_LINE_STRIP = 0x83: A series of connected line primitives, with consecutive lines sharing a vertex.

enumerator TL_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST = 0x04: A series of separate triangle primitives.

enumerator TL_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP = 0x85: A series of connected triangle primitives, with consecutive triangles sharing an edge.

enumerator TL_PRIMITIVE_TOPOLOGY_TRIANGLE_FAN = 0x06: A series of connected triangle primitives, with triangles sharing a common vertex.

enumerator TL_PRIMITIVE_TOPOLOGY_LINE_LIST_ADJACENCY = 0x07: A series of separate line primitives with adjacency.

enumerator TL_PRIMITIVE_TOPOLOGY_LINE_STRIP_ADJACENCY = 0x88: A series of connected line primitives with adjacency, with consecutive primitives sharing three vertices.

enumerator TL_PRIMITIVE_TOPOLOGY_TRIANGLE_LIST_ADJACENCY = 0x09: A series of separate triangle primitives with adjacency.

enumerator TL_PRIMITIVE_TOPOLOGY_TRIANGLE_STRIP_ADJACENCY = 0x8A: A series of connected triangle primitives with adjacency, with consecutive primitives sharing an edge.

enumerator TL_PRIMITIVE_TOPOLOGY_PATCH_LIST = 0x0B: Separate patch primitives.

enumerator TL_PRIMITIVE_TOPOLOGY_NULL = 0x00: Null primitive topology.

enum TL_PolygonMode_t

Enumeration of polygon rasterization modes.

This enumeration contains supported modes of polygon filling by the rasterizer.

Values:

enumerator TL_POLYGON_MODE_FILL: Draw filled polygons.

enumerator TL_POLYGON_MODE_WIREFRAME: Draw polygon edges (wireframe) only.

enumerator TL_POLYGON_MODE_POINT: Draw vertex points only.