Graphics

February 6, 2022 · View on GitHub

This document shows off the graphics API provided by gunslinger.

Functions

Resource Creation:

The following functions are used for creating resources, such as vertex buffers, textures, uniforms, etc.

gs_graphics_texture_create

Creates a texture resource.

gs_handle(gs_graphics_texture_t)
gs_graphics_texture_create(
    const gs_graphics_texture_desc_t* desc
);

Parameters:

desc

A pointer to a gs_graphics_texture_desc_t structure that describes the texture to be created.

Return Value:

Returns a handle to a texture resource.

gs_graphics_uniform_create

Creates a uniform resource.

gs_handle(gs_graphics_uniform_t)
gs_graphics_uniform_create(
    const gs_graphics_uniform_desc_t* desc
);

Parameters:

desc

A pointer to a gs_graphics_uniform_desc_t structure that describes the uniform to be created.

Return Value:

Returns a handle to a uniform resource.

gs_graphics_shader_create

Creates a shader resource.

gs_handle(gs_graphics_shader_t)
gs_graphics_shader_create(
    const gs_graphics_shader_desc_t* desc
);

Parameters:

desc

A pointer to a gs_graphics_shader_desc_t structure that describes the shader to be created.

Return Value:

Returns a handle to a shader resource.

gs_graphics_vertex_buffer_create

Creates a vertex buffer resource.

gs_handle(gs_graphics_vertex_buffer_t)
gs_graphics_vertex_buffer_create(
    const gs_graphics_vertex_buffer_desc_t* desc
);

Parameters:

desc

A pointer to a gs_graphics_vertex_buffer_desc_t structure that describes the vertex buffer to be created.

Return Value:

Returns a handle to a vertex buffer resource.

gs_graphics_index_buffer_create

Creates an index buffer resource.

gs_handle(gs_graphics_index_buffer_t)
gs_graphics_index_buffer_create(
    const gs_graphics_index_buffer_desc_t* desc
);

Parameters:

desc

A pointer to a gs_graphics_index_buffer_desc_t structure that describes the index buffer to be created.

Return Value:

Returns a handle to an index buffer resource.

gs_graphics_uniform_buffer_create

Creates a uniform buffer resource.

gs_handle(gs_graphics_uniform_buffer_t)
gs_graphics_uniform_buffer_create(
    const gs_graphics_uniform_buffer_desc_t* desc
);

Parameters:

desc

A pointer to a gs_graphics_uniform_buffer_desc_t structure that describes the uniform buffer to be created.

Return Value:

Returns a handle to a uniform buffer resource.

gs_graphics_framebuffer_create

Creates a framebuffer resource.

gs_handle(gs_graphics_framebuffer_t)
gs_graphics_framebuffer_create(
    const gs_graphics_framebuffer_desc_t* desc
);

Parameters:

desc

A pointer to a gs_graphics_framebuffer_desc_t structure that describes the framebuffer to be created.

Return Value:

Returns a handle to a framebuffer resource.

gs_graphics_render_pass_create

Creates a render-pass resource.

gs_handle(gs_graphics_render_pass_t)
gs_graphics_render_pass_create(
    const gs_graphics_render_pass_desc_t* desc
);

Parameters:

desc

A pointer to a gs_graphics_render_pass_desc_t structure that describes the render-pass to be created.

Return Value:

Returns a handle to a render-pass resource.

gs_graphics_pipeline_create

Creates a pipeline resource.

gs_handle(gs_graphics_pipeline_t)
gs_graphics_pipeline_create(
    const gs_graphics_pipeline_desc_t* desc
);

Parameters:

desc

A pointer to a gs_graphics_pipeline_desc_t structure that describes the pipeline to be created

Return Value:

Returns a handle to a pipeline resource.

Resource Destruction:

The following functions are used for freeing resources that were created with the above functions.

gs_graphics_texture_destroy

Destroys a texture resource.

void gs_graphics_texture_destroy(
    gs_handle(gs_graphics_texture_t) hndl
);

Parameters:

hndl

A handle to a texture resource.

Return Value:

None

gs_graphics_shader_destroy

Destroys a shader resource.

void gs_graphics_shader_destroy(
    gs_handle(gs_graphics_shader_t) hndl
);

Parameters:

hndl

A handle to a shader resource.

Return Value:

None

gs_graphics_render_pass_destroy

Destroys a render-pass resource.

void gs_graphics_render_pass_destroy(
    gs_handle(gs_graphics_render_pass_t) hndl
);

Parameters:

hndl

A handle to a render-pass resource.

Return Value:

None

gs_graphics_pipeline_destroy

Destroys a pipeline resource.

void gs_graphics_pipeline_destroy(
    gs_handle(gs_graphics_pipeline_t) hndl
);

Parameters:

hndl

A handle to a pipeline resource.

Return Value:

None

Structures

gs_graphics_shader_source_desc_t

Describes the source data for a shader resource.

typedef struct gs_graphics_shader_source_desc_t
{
    gs_graphics_shader_stage_type       type;
    const char*                         source;
} gs_graphics_shader_source_desc_t;

Members

type

Indicates what stage the shader code is for (ie, vertex, fragment, etc.)

source

Source code for GLSL shader, as an ASCII string.

gs_graphics_shader_desc_t

Describes a shader resource.

typedef struct gs_graphics_shader_desc_t
{
    gs_graphics_shader_source_desc_t*       sources;
    size_t                                  size;
    char                                    name[64];
} gs_graphics_shader_desc_t;

Members

sources

Array of gs_graphics_shader_source_desc_t containing shader sources.

size

Size in bytes of the shader source desc array.

name

Optional name for the shader - used internally for logging/debugging.

gs_graphics_texture_desc_t

Describes a texture resource.

typedef struct gs_graphics_texture_desc_t
{
    uint32_t                                width;
    uint32_t                                height;
    gs_graphics_texture_format_type         format;
    gs_graphics_texture_wrapping_type       wrap_s;
    gs_graphics_texture_wrapping_type       wrap_t;
    gs_graphics_texture_filtering_type      min_filter;
    gs_graphics_texture_filtering_type      mag_filter;
    gs_graphics_texture_filtering_type      mip_filter;
    void*                                   data;
    b32                                     render_target;
} gs_graphics_texture_desc_t;

Members

width

Width of texture in pixels.

height

Height of texture in pixels.

format

Format of texture data (rgba32, rgba8, rgba32f, r8, depth32f, etc...).

wrap_s

Wrapping type for s (or u) axis of texture.

wrap_t

Wrapping type for t (or v) axis of texture.

min_filter

Minification filter for texture.

mag_filter

Magnification filter for texture.

mip_filter

Mip filter for texture.

num_mips

Number of mips to generate (default 0 is disable mip generation).

data

Texture data to upload (can be NULL).

render_target

Default to false (not a render target).

gs_graphics_uniform_layout_desc_t

DESC

Members

gs_graphics_uniform_desc_t

DESC

Members

gs_graphics_buffer_update_desc_t

DESC

Members

gs_graphics_buffer_base_desc_t

DESC

Members

gs_graphics_vertex_buffer_desc_t

Describes a vertex buffer resource.

typedef struct gs_graphics_vertex_buffer_desc_t
{
    void*                                   data;
    size_t                                  size;
    gs_graphics_buffer_usage_type           usage;
    gs_graphics_buffer_update_desc_t        update;
} gs_graphics_vertex_buffer_desc_t;

Members

data

Data to fill the vertex buffer with. Optional; can be NULL.

size

Size in bytes of the vertex buffer to be created.

usage

Specifies how the buffer's contents may be updated over time. See associated enum.

update

Specifies how the buffer's are to be updated with gs_graphics_vertex_buffer_update(). See associated enum.

gs_graphics_index_buffer_desc_t

Describes an index buffer resource.

typedef gs_graphics_vertex_buffer_desc_t gs_graphics_index_buffer_desc_t;

Members

See definition of gs_graphics_vertex_buffer_desc_t. NOTE: update specifies use for gs_graphics_index_buffer_update().

gs_graphics_uniform_buffer_desc_t

Describes a uniform buffer resource.

typedef struct gs_graphics_uniform_buffer_desc_t
{
    void*                                   data;
    size_t                                  size;
    gs_graphics_buffer_usage_type           usage;
    const char*                             name;
    gs_graphics_shader_stage_type           stage;
    gs_graphics_buffer_update_desc_t        update;
} gs_graphics_uniform_buffer_desc_t;

Members

data

Data to fill the vertex buffer with. Optional; can be NULL.

size

Size in bytes of the vertex buffer to be created.

usage

Specifies how the buffer's contents may be updated over time. See associated enum.

name

Name for the buffer; optional, but required for OpenGL/ES & WebGL.

stage

Pipeline stage the buffer is to be bound to (ie, vertex, fragment, etc.)

update

Specifies how the buffer is to be updated.

gs_graphics_framebuffer_desc_t

Describes a framebuffer resource.

typedef struct gs_graphics_framebuffer_desc_t
{
    void*       data;
} gs_graphics_framebuffer_desc_t;

Members

data

Data to fill the framebuffer with; optional, can be NULL.

gs_graphics_clear_action_t

Describes the action for clearing the current render target's buffers.

typedef struct gs_graphics_clear_action_t
{
    gs_graphics_clear_flag      flag;   // Flag to be set (clear color, clear depth, clear stencil, clear all)
    union
    {
        float       color[4];            // Clear color value
        float       depth;               // Clear depth value
        int32_t     stencil;           // Clear stencil value
    };
 } gs_graphics_clear_action_t;

Members

flag

Specifies which buffers are to be cleared (color, depth, stencil). Can be OR'd (||) together.

color

Value to clear the color buffer with.

depth

Value to clear the depth buffer with.

stencil

Value to clear the stencil buffer with.

gs_graphics_clear_desc_t

Describes a set of clear actions to be performed.

typedef struct gs_graphics_clear_desc_t
{
    gs_graphics_clear_action_t*     actions;
    size_t                          size;
} gs_graphics_clear_desc_t;

Members

actions

Array of clear actions.

size

Size of clear action array in bytes.

gs_graphics_render_pass_desc_t

Describes a render-pass resource.

typedef struct gs_graphics_render_pass_desc_t
{
    gs_handle(gs_graphics_framebuffer_t)        fbo;
    gs_handle(gs_graphics_texture_t)*           color;
    size_t                                      color_size;
    gs_handle(gs_graphics_texture_t)            depth;
    gs_handle(gs_graphics_texture_t)            stencil;
} gs_graphics_render_pass_desc_t;

Members

fbo

Framebuffer to bind for render-pass.

color

Array of color attachments to be bound (useful for MRT, if supported).

color_size

Size of color attachment array.

depth

Depth attachment to be bound.

stencil

Stencil attachment to be bound.

gs_graphics_bind_vertex_buffer_desc_t

Describes how a vertex buffer is to be bound to the pipeline.

typedef struct gs_graphics_bind_vertex_buffer_desc_t
{
    gs_handle(gs_graphics_vertex_buffer_t)      buffer;
    size_t                                      offset;
    gs_graphics_vertex_data_type                data_type;
} gs_graphics_bind_vertex_buffer_desc_t;

Members

buffer

Handle to the vertex buffer to be bound.

offset

Offset into the buffer to bind from.

data_type

Specifies if the data is interleaved or non-interleaved.

gs_graphics_bind_index_buffer_desc_t

Describes how an index buffer is to be bound to the pipeline.

typedef struct gs_graphics_bind_index_buffer_desc_t
{
    gs_handle(gs_graphics_index_buffer_t)       buffer;
} gs_graphics_bind_index_buffer_desc_t;

Members

buffer

Handle to the index buffer to be bound.

gs_graphics_bind_image_buffer_desc_t

Specifies how an image buffer is to be bound to the pipeline.

typedef struct gs_graphics_bind_image_buffer_desc_t
{
    gs_handle(gs_graphics_texture_t)        tex;
    uint32_t                                binding;
    gs_graphics_access_type                 access;
} gs_graphics_bind_image_buffer_desc_t;

Members

tex

Handle to the image buffer's texture to be bound.

binding

Slot to bind the texture to.

access

Specifies read/write permissions.

gs_graphics_bind_uniform_buffer_desc_t

Specifies how a uniform buffer is to be bound to the pipeline.

typedef struct gs_graphics_bind_uniform_buffer_desc_t
{
    gs_handle(gs_graphics_uniform_buffer_t)     buffer;
    uint32_t                                    binding;
    struct
    {
        size_t                                  offset;
        size_t                                  size;
    } range;
} gs_graphics_bind_uniform_buffer_desc_t;

Members

buffer

Handle to the uniform buffer to be bound.

binding

Slot to bind the uniform buffer to.

offset

Specify an offset for ranged binds.

size

Specify size for ranged binds.

gs_graphics_bind_uniform_desc_t

Specifies how a uniform is to be bound to the pipeline.

typedef struct gs_graphics_bind_uniform_desc_t
{
    gs_handle(gs_graphics_uniform_t)        uniform;
    void*                                   data;
    uint32_t                                binding;   // Base binding for samplers?
} gs_graphics_bind_uniform_desc_t;

Members

uniform

Handle to the uniform to be bound.

data

Data to be attached to the uniform.

binding

Slot to bind the uniform to. (NOTE: base binding for samplers)?

gs_graphics_bind_desc_t

Specifies a set of bindings to apply to the pipeline.

typedef struct gs_graphics_bind_desc_t
{
    struct {
        gs_graphics_bind_vertex_buffer_desc_t*      desc;
        size_t                                      size;
    } vertex_buffers;

    struct {
        gs_graphics_bind_index_buffer_desc_t*       desc;
        size_t                                      size;
    } index_buffers;

    struct {
        gs_graphics_bind_uniform_buffer_desc_t*     desc;
        size_t                                      size;
    } uniform_buffers;

    struct {
        gs_graphics_bind_uniform_desc_t*            desc;
        size_t                                      size;
    } uniforms;

    struct {
        gs_graphics_bind_image_buffer_desc_t*       desc;
        size_t                                      size;
    } image_buffers;
} gs_graphics_bind_desc_t;

Members

desc

Array of declarations (NULL by default).

size

Size of array in bytes (optional if one is specified).

gs_graphics_blend_state_desc_t

Specifies a blend state.

typedef struct gs_graphics_blend_state_desc_t
{
    gs_graphics_blend_equation_type     func;
    gs_graphics_blend_mode_type         src;
    gs_graphics_blend_mode_type         dst;
} gs_graphics_blend_state_desc_t;

Members

func

Equation function to use for blend ops.

src

Source blend mode.

dst

Destination blend mode.

gs_graphics_depth_state_desc_t

Specifies a depth state.

typedef struct gs_graphics_depth_state_desc_t
{
    gs_graphics_depth_func_type     func;
} gs_graphics_depth_state_desc_t;

Members

func

Function to set for depth test.

gs_graphics_stencil_state_desc_t

Specifies a stencil state.

typedef struct gs_graphics_stencil_state_desc_t
{
    gs_graphics_stencil_func_type       func;
    uint32_t                            ref;
    uint32_t                            comp_mask;
    uint32_t                            write_mask;
    gs_graphics_stencil_op_type         sfail;
    gs_graphics_stencil_op_type         dpfail;
    gs_graphics_stencil_op_type         dppass;
} gs_graphics_stencil_state_desc_t;

Members

func

Function to set for stencil test.

ref

Specifies reference val for stencil test.

comp_mask

Specifies mask that is ANDed with both ref val and stored stencil val.

write_mask

Specifies mask that is ANDed with both ref val and stored stencil val.

sfail

Action to take when stencil test fails.

dpfail

Action to take when stencil test passes but depth test fails.

dppass

Action to take when both stencil test passes and either depth passes or is not enabled.