This document shows off the graphics API provided by gunslinger.
The following functions are used for creating resources, such as vertex buffers, textures, uniforms, etc.
- gs_graphics_texture_create
- gs_graphics_uniform_create
- gs_graphics_shader_create
- gs_graphics_vertex_buffer_create
- gs_graphics_index_buffer_create
- gs_graphics_uniform_buffer_create
- gs_graphics_storage_buffer_create
- gs_graphics_framebuffer_create
- gs_graphics_render_pass_create
- gs_graphics_pipeline_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.
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.
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.
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.
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.
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.
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.
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.
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.
The following functions are used for freeing resources that were created with the above functions.
- gs_graphics_vertex_buffer_destroy
- gs_graphics_index_buffer_destroy
- gs_graphics_texture_destroy
- gs_graphics_uniform_destroy
- gs_graphics_uniform_buffer_destroy
- gs_graphics_storage_buffer_destroy
- gs_graphics_shader_destroy
- gs_graphics_render_pass_destroy
- gs_graphics_pipeline_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
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
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
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
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.
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.
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).
DESC
Members
DESC
Members
DESC
Members
DESC
Members
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.
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().
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.
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.
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.
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.
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.
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.
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.
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.
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.
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)?
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).
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.
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.
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.
DESC
Members
DESC
Members
DESC
Members
DESC
Members
DESC
Members
DESC
Members