Core Graphics API

#include <graphics/graphics.h>

Graphics Enumerations

enum gs_draw_mode

Draw mode. Can be one of the following values:

  • GS_POINTS - Draws points

  • GS_LINES - Draws individual lines

  • GS_LINESTRIP - Draws a line strip

  • GS_TRIS - Draws individual triangles

  • GS_TRISTRIP - Draws a triangle strip

enum gs_color_format

Color format. Can be one of the following values:

  • GS_UNKNOWN - Unknown format

  • GS_A8 - 8 bit alpha channel only

  • GS_R8 - 8 bit red channel only

  • GS_RGBA - RGBA, 8 bits per channel

  • GS_BGRX - BGRX, 8 bits per channel

  • GS_BGRA - BGRA, 8 bits per channel

  • GS_R10G10B10A2 - RGBA, 10 bits per channel except alpha, which is 2 bits

  • GS_RGBA16 - RGBA, 16 bits per channel

  • GS_R16 - 16 bit red channel only

  • GS_RGBA16F - RGBA, 16 bit floating point per channel

  • GS_RGBA32F - RGBA, 32 bit floating point per channel

  • GS_RG16F - 16 bit floating point red and green channels only

  • GS_RG32F - 32 bit floating point red and green channels only

  • GS_R16F - 16 bit floating point red channel only

  • GS_R32F - 32 bit floating point red channel only

  • GS_DXT1 - Compressed DXT1

  • GS_DXT3 - Compressed DXT3

  • GS_DXT5 - Compressed DXT5

  • GS_RGBA_UNORM - RGBA, 8 bits per channel, no SRGB aliasing

  • GS_BGRX_UNORM - BGRX, 8 bits per channel, no SRGB aliasing

  • GS_BGRA_UNORM - BGRA, 8 bits per channel, no SRGB aliasing

  • GS_RG16 - RG, 16 bits per channel

enum gs_color_space

Color space. Can be one of the following values:

  • GS_CS_SRGB - sRGB

  • GS_CS_SRGB_16F - High-precision SDR

  • GS_CS_709_EXTENDED - Canvas, Mac EDR (HDR)

  • GS_CS_709_SCRGB - 1.0 = 80 nits, Windows/Linux HDR

enum gs_zstencil_format

Z-Stencil buffer format. Can be one of the following values:

  • GS_ZS_NONE - No Z-stencil buffer

  • GS_Z16 - 16 bit Z buffer

  • GS_Z24_S8 - 24 bit Z buffer, 8 bit stencil

  • GS_Z32F - 32 bit floating point Z buffer

  • GS_Z32F_S8X24 - 32 bit floating point Z buffer, 8 bit stencil

enum gs_index_type

Index buffer type. Can be one of the following values:

  • GS_UNSIGNED_SHORT - 16 bit index

  • GS_UNSIGNED_LONG - 32 bit index

enum gs_cull_mode

Cull mode. Can be one of the following values:

  • GS_BACK - Cull back faces

  • GS_FRONT - Cull front faces

  • GS_NEITHER - Cull neither

enum gs_blend_type

Blend type. Can be one of the following values:

  • GS_BLEND_ZERO

  • GS_BLEND_ONE

  • GS_BLEND_SRCCOLOR

  • GS_BLEND_INVSRCCOLOR

  • GS_BLEND_SRCALPHA

  • GS_BLEND_INVSRCALPHA

  • GS_BLEND_DSTCOLOR

  • GS_BLEND_INVDSTCOLOR

  • GS_BLEND_DSTALPHA

  • GS_BLEND_INVDSTALPHA

  • GS_BLEND_SRCALPHASAT

enum gs_depth_test

Depth test type. Can be one of the following values:

  • GS_NEVER

  • GS_LESS

  • GS_LEQUAL

  • GS_EQUAL

  • GS_GEQUAL

  • GS_GREATER

  • GS_NOTEQUAL

  • GS_ALWAYS

enum gs_stencil_side

Stencil side. Can be one of the following values:

  • GS_STENCIL_FRONT=1

  • GS_STENCIL_BACK

  • GS_STENCIL_BOTH

enum gs_stencil_op_type

Stencil operation type. Can be one of the following values:

  • GS_KEEP

  • GS_ZERO

  • GS_REPLACE

  • GS_INCR

  • GS_DECR

  • GS_INVERT

enum gs_cube_sides

Cubemap side. Can be one of the following values:

  • GS_POSITIVE_X

  • GS_NEGATIVE_X

  • GS_POSITIVE_Y

  • GS_NEGATIVE_Y

  • GS_POSITIVE_Z

  • GS_NEGATIVE_Z

enum gs_sample_filter

Sample filter type. Can be one of the following values:

  • GS_FILTER_POINT

  • GS_FILTER_LINEAR

  • GS_FILTER_ANISOTROPIC

  • GS_FILTER_MIN_MAG_POINT_MIP_LINEAR

  • GS_FILTER_MIN_POINT_MAG_LINEAR_MIP_POINT

  • GS_FILTER_MIN_POINT_MAG_MIP_LINEAR

  • GS_FILTER_MIN_LINEAR_MAG_MIP_POINT

  • GS_FILTER_MIN_LINEAR_MAG_POINT_MIP_LINEAR

  • GS_FILTER_MIN_MAG_LINEAR_MIP_POINT

enum gs_address_mode

Address mode. Can be one of the following values:

  • GS_ADDRESS_CLAMP

  • GS_ADDRESS_WRAP

  • GS_ADDRESS_MIRROR

  • GS_ADDRESS_BORDER

  • GS_ADDRESS_MIRRORONCE

enum gs_texture_type

Texture type. Can be one of the following values:

  • GS_TEXTURE_2D

  • GS_TEXTURE_3D

  • GS_TEXTURE_CUBE

Graphics Structures

struct gs_monitor_info
int gs_monitor_info.rotation_degrees
long gs_monitor_info.x
long gs_monitor_info.y
long gs_monitor_info.cx
long gs_monitor_info.cy

struct gs_tvertarray
size_t gs_tvertarray.width
void *gs_tvertarray.array

struct gs_vb_data
size_t gs_vb_data.num
struct vec3 *gs_vb_data.points
struct vec3 *gs_vb_data.normals
struct vec3 *gs_vb_data.tangents
uint32_t *gs_vb_data.colors
size_t gs_vb_data.num_tex
struct gs_tvertarray *gs_vb_data.tvarray

struct gs_sampler_info
enum gs_sample_filter gs_sampler_info.filter
enum gs_address_mode gs_sampler_info.address_u
enum gs_address_mode gs_sampler_info.address_v
enum gs_address_mode gs_sampler_info.address_w
int gs_sampler_info.max_anisotropy
uint32_t gs_sampler_info.border_color

struct gs_display_mode
uint32_t gs_display_mode.width
uint32_t gs_display_mode.height
uint32_t gs_display_mode.bits
uint32_t gs_display_mode.freq

struct gs_rect
int gs_rect.x
int gs_rect.y
int gs_rect.cx
int gs_rect.cy

struct gs_window

A window structure. This structure is used with a native widget.

void *gs_window.hwnd

(Windows only) an HWND widget.

id gs_window.view

(macOS only) A view ID.

uint32_t gs_window.id
void *gs_window.display

(Linux only) Window ID and display


struct gs_init_data

Swap chain initialization data.

struct gs_window gs_init_data.window
uint32_t gs_init_data.cx
uint32_t gs_init_data.cy
uint32_t gs_init_data.num_backbuffers
enum gs_color_format gs_init_data.format
enum gs_zstencil_format gs_init_data.zsformat
uint32_t gs_init_data.adapter

Initialization Functions

void gs_enum_adapters(bool (*callback)(void *param, const char *name, uint32_t id), void *param)

Enumerates adapters (this really only applies on Windows).

Parameters:
  • callback – Enumeration callback

  • param – Private data passed to the callback


int gs_create(graphics_t **graphics, const char *module, uint32_t adapter)

Creates a graphics context

Parameters:
  • graphics – Pointer to receive the graphics context

  • module – Module name

  • adapter – Adapter index

Returns:

Can return one of the following values:

  • GS_SUCCESS

  • GS_ERROR_FAIL

  • GS_ERROR_MODULE_NOT_FOUND

  • GS_ERROR_NOT_SUPPORTED


void gs_destroy(graphics_t *graphics)

Destroys a graphics context

Parameters:
  • graphics – Graphics context


void gs_enter_context(graphics_t *graphics)

Enters and locks the graphics context

Parameters:
  • graphics – Graphics context


void gs_leave_context(void)

Leaves and unlocks the graphics context

Parameters:
  • graphics – Graphics context


graphics_t *gs_get_context(void)
Returns:

The currently locked graphics context for this thread


Matrix Stack Functions

void gs_matrix_push(void)

Pushes the matrix stack and duplicates the current matrix.


void gs_matrix_pop(void)

Pops the current matrix from the matrix stack.


void gs_matrix_identity(void)

Sets the current matrix to an identity matrix.


void gs_matrix_transpose(void)

Transposes the current matrix.


void gs_matrix_set(const struct matrix4 *matrix)

Sets the current matrix.

Parameters:
  • matrix – The matrix to set


void gs_matrix_get(struct matrix4 *dst)

Gets the current matrix

Parameters:
  • dst – Destination matrix


void gs_matrix_mul(const struct matrix4 *matrix)

Multiplies the current matrix

Parameters:
  • matrix – Matrix to multiply the current stack matrix with


void gs_matrix_rotquat(const struct quat *rot)

Multiplies the current matrix with a quaternion

Parameters:
  • rot – Quaternion to multiple the current matrix stack with


void gs_matrix_rotaa(const struct axisang *rot)
void gs_matrix_rotaa4f(float x, float y, float z, float angle)

Multiplies the current matrix with an axis angle

Parameters:
  • rot – Axis angle to multiple the current matrix stack with


void gs_matrix_translate(const struct vec3 *pos)
void gs_matrix_translate3f(float x, float y, float z)

Translates the current matrix

Parameters:
  • pos – Vector to translate the current matrix stack with


void gs_matrix_scale(const struct vec3 *scale)
void gs_matrix_scale3f(float x, float y, float z)

Scales the current matrix

Parameters:
  • scale – Scale value to scale the current matrix stack with


Draw Functions

gs_effect_t *gs_get_effect(void)
Returns:

The currently active effect, or NULL if none active


void gs_draw_sprite(gs_texture_t *tex, uint32_t flip, uint32_t width, uint32_t height)

Draws a 2D sprite. Sets the “image” parameter of the current effect to the texture and renders a quad.

If width or height is 0, the width or height of the texture will be used. The flip value specifies whether the texture should be flipped on the U or V axis with GS_FLIP_U and GS_FLIP_V.

Parameters:
  • tex – Texture to draw

  • flip

    Can be 0 or a bitwise-OR combination of one of the following values:

    • GS_FLIP_U - Flips the texture horizontally

    • GS_FLIP_V - Flips the texture vertically

  • width – Width

  • height – Height


void gs_draw_sprite_subregion(gs_texture_t *tex, uint32_t flip, uint32_t x, uint32_t y, uint32_t cx, uint32_t cy)

Draws a subregion of a 2D sprite. Sets the “image” parameter of the current effect to the texture and renders a quad.

Parameters:
  • tex – Texture to draw

  • flip

    Can be 0 or a bitwise-OR combination of one of the following values:

    • GS_FLIP_U - Flips the texture horizontally

    • GS_FLIP_V - Flips the texture vertically

  • x – X value within subregion

  • y – Y value within subregion

  • cx – CX value of subregion

  • cy – CY value of subregion


void gs_reset_viewport(void)

Sets the viewport to current swap chain size


void gs_set_2d_mode(void)

Sets the projection matrix to a default screen-sized orthographic mode


void gs_set_3d_mode(double fovy, double znear, double zfar)

Sets the projection matrix to a default screen-sized perspective mode

Parameters:
  • fovy – Field of view (in degrees)

  • znear – Near plane

  • zfar – Far plane


void gs_viewport_push(void)

Pushes/stores the current viewport


void gs_viewport_pop(void)

Pops/recalls the last pushed viewport


void gs_perspective(float fovy, float aspect, float znear, float zfar)

Sets the projection matrix to a perspective mode

Parameters:
  • fovy – Field of view (in degrees)

  • aspect – Aspect ratio

  • znear – Near plane

  • zfar – Far plane


void gs_blend_state_push(void)

Pushes/stores the current blend state


void gs_blend_state_pop(void)

Pops/restores the last blend state


void gs_reset_blend_state(void)

Sets the blend state to the default value: source alpha and invert source alpha.


Swap Chains

gs_swapchain_t *gs_swapchain_create(const struct gs_init_data *data)

Creates a swap chain (display view on a native widget)

Parameters:
  • data – Swap chain initialization data

Returns:

New swap chain object, or NULL if failed


void gs_swapchain_destroy(gs_swapchain_t *swapchain)

Destroys a swap chain


void gs_resize(uint32_t cx, uint32_t cy)

Resizes the currently active swap chain

Parameters:
  • cx – New width

  • cy – New height


void gs_update_color_space(void)

Updates the color space of the swap chain based on the HDR status of the nearest monitor


void gs_get_size(uint32_t *cx, uint32_t *cy)

Gets the size of the currently active swap chain

Parameters:
  • cx – Pointer to receive width

  • cy – Pointer to receive height


uint32_t gs_get_width(void)

Gets the width of the currently active swap chain


uint32_t gs_get_height(void)

Gets the height of the currently active swap chain


Resource Loading

void gs_load_vertexbuffer(gs_vertbuffer_t *vertbuffer)

Loads a vertex buffer

Parameters:
  • vertbuffer – Vertex buffer to load, or NULL to unload


void gs_load_indexbuffer(gs_indexbuffer_t *indexbuffer)

Loads a index buffer

Parameters:
  • indexbuffer – Index buffer to load, or NULL to unload


void gs_load_texture(gs_texture_t *tex, int unit)

Loads a texture (this is usually not called manually)

Parameters:
  • tex – Texture to load, or NULL to unload

  • unit – Texture unit to load texture for


void gs_load_samplerstate(gs_samplerstate_t *samplerstate, int unit)

Loads a sampler state (this is usually not called manually)

Parameters:
  • samplerstate – Sampler state to load, or NULL to unload

  • unit – Texture unit to load sampler state for


void gs_load_swapchain(gs_swapchain_t *swapchain)

Loads a swapchain

Parameters:
  • swapchain – Swap chain to load, or NULL to unload


Draw Functions

enum gs_color_space gs_get_color_space(void)
Returns:

The currently active color space


gs_texture_t *gs_get_render_target(void)
Returns:

The currently active render target


gs_zstencil_t *gs_get_zstencil_target(void)
Returns:

The currently active Z-stencil target


void gs_set_render_target(gs_texture_t *tex, gs_zstencil_t *zstencil)

Sets the active render target with implicit GS_CS_SRGB color space

Parameters:
  • tex – Texture to set as the active render target

  • zstencil – Z-stencil to use as the active render target


void gs_set_render_target_with_color_space(gs_texture_t *tex, gs_zstencil_t *zstencil, enum gs_color_space space)

Sets the active render target along with color space

Parameters:
  • tex – Texture to set as the active render target

  • zstencil – Z-stencil to use as the active render target

  • space – Color space of the render target


void gs_set_cube_render_target(gs_texture_t *cubetex, int side, gs_zstencil_t *zstencil)

Sets a cubemap side as the active render target

Parameters:
  • cubetex – Cubemap

  • side – Cubemap side

  • zstencil – Z-stencil buffer, or NULL if none


void gs_copy_texture(gs_texture_t *dst, gs_texture_t *src)

Copies a texture

Parameters:
  • dst – Destination texture

  • src – Source texture


void gs_stage_texture(gs_stagesurf_t *dst, gs_texture_t *src)

Copies a texture to a staging surface and copies it to RAM. Ideally best to give this a frame to process to prevent stalling.

Parameters:
  • dst – Staging surface

  • src – Texture to stage


void gs_begin_scene(void)
void gs_end_scene(void)

Begins/ends a scene (this is automatically called by libobs, there’s no need to call this manually).


void gs_draw(enum gs_draw_mode draw_mode, uint32_t start_vert, uint32_t num_verts)

Draws a primitive or set of primitives.

Parameters:
  • draw_mode – The primitive draw mode to use

  • start_vert – Starting vertex index

  • num_verts – Number of vertices


void gs_clear(uint32_t clear_flags, const struct vec4 *color, float depth, uint8_t stencil)

Clears color/depth/stencil buffers.

Parameters:
  • clear_flags

    Flags to clear with. Can be one of the following values:

    • GS_CLEAR_COLOR - Clears color buffer

    • GS_CLEAR_DEPTH - Clears depth buffer

    • GS_CLEAR_STENCIL - Clears stencil buffer

  • color – Color value to clear the color buffer with

  • depth – Depth value to clear the depth buffer with

  • stencil – Stencil value to clear the stencil buffer with


void gs_present(void)

Displays what was rendered on to the current render target


void gs_flush(void)

Flushes GPU calls


void gs_set_cull_mode(enum gs_cull_mode mode)

Sets the current cull mode.

Parameters:
  • mode – Cull mode


enum gs_cull_mode gs_get_cull_mode(void)
Returns:

The current cull mode


void gs_enable_blending(bool enable)

Enables/disables blending

Parameters:
  • enabletrue to enable, false to disable


void gs_enable_depth_test(bool enable)

Enables/disables depth testing

Parameters:
  • enabletrue to enable, false to disable


void gs_enable_stencil_test(bool enable)

Enables/disables stencil testing

Parameters:
  • enabletrue to enable, false to disable


void gs_enable_stencil_write(bool enable)

Enables/disables stencil writing

Parameters:
  • enabletrue to enable, false to disable


void gs_enable_color(bool red, bool green, bool blue, bool alpha)

Enables/disables specific color channels

Parameters:
  • redtrue to enable red channel, false to disable

  • greentrue to enable green channel, false to disable

  • bluetrue to enable blue channel, false to disable

  • alphatrue to enable alpha channel, false to disable


void gs_blend_function(enum gs_blend_type src, enum gs_blend_type dest)

Sets the blend function’s source and destination factors

Parameters:
  • src – Blend type for the blending equation’s source factors

  • dest – Blend type for the blending equation’s destination factors


void gs_blend_function_separate(enum gs_blend_type src_c, enum gs_blend_type dest_c, enum gs_blend_type src_a, enum gs_blend_type dest_a)

Sets the blend function’s source and destination factors for RGB and alpha separately

Parameters:
  • src_c – Blend type for the blending equation’s source RGB factor

  • dest_c – Blend type for the blending equation’s destination RGB factor

  • src_a – Blend type for the blending equation’s source alpha factor

  • dest_a – Blend type for the blending equation’s destination alpha factor


void gs_blend_op(enum gs_blend_op_type op)

Sets the blend function’s operation type

Parameters:
  • op – Operation type for the blending equation


void gs_depth_function(enum gs_depth_test test)

Sets the depth function

Parameters:
  • test – Sets the depth test type


void gs_stencil_function(enum gs_stencil_side side, enum gs_depth_test test)

Sets the stencil function

Parameters:
  • side – Stencil side

  • test – Depth test


void gs_stencil_op(enum gs_stencil_side side, enum gs_stencil_op_type fail, enum gs_stencil_op_type zfail, enum gs_stencil_op_type zpass)

Sets the stencil operation

Parameters:
  • side – Stencil side

  • fail – Operation to perform on stencil test failure

  • zfail – Operation to perform on depth test failure

  • zpass – Operation to perform on depth test success


void gs_set_viewport(int x, int y, int width, int height)

Sets the current viewport

Parameters:
  • x – X position relative to upper left

  • y – Y position relative to upper left

  • width – Width of the viewport

  • height – Height of the viewport


void gs_get_viewport(struct gs_rect *rect)

Gets the current viewport

Parameters:
  • rect – Pointer to receive viewport rectangle


void gs_set_scissor_rect(const struct gs_rect *rect)

Sets or clears the current scissor rectangle

Rect:

Scissor rectangle, or NULL to clear


void gs_ortho(float left, float right, float top, float bottom, float znear, float zfar)

Sets the projection matrix to an orthographic matrix


void gs_frustum(float left, float right, float top, float bottom, float znear, float zfar)

Sets the projection matrix to a frustum matrix


void gs_projection_push(void)

Pushes/stores the current projection matrix


void gs_projection_pop(void)

Pops/restores the last projection matrix pushed


Texture Functions

gs_texture_t *gs_texture_create(uint32_t width, uint32_t height, enum gs_color_format color_format, uint32_t levels, const uint8_t **data, uint32_t flags)

Creates a texture.

Parameters:
  • width – Width

  • height – Height

  • color_format – Color format

  • levels – Number of total texture levels. Set to 1 if no mip-mapping

  • data – Pointer to array of texture data pointers

  • flags

    Can be 0 or a bitwise-OR combination of one or more of the following value:

    • GS_BUILD_MIPMAPS - Automatically builds mipmaps (Note: not fully tested)

    • GS_DYNAMIC - Dynamic

    • GS_RENDER_TARGET - Render target

Returns:

A new texture object


gs_texture_t *gs_texture_create_from_file(const char *file)

Creates a texture from a file. Note that this isn’t recommended for animated gifs – instead use the Image File Helper.

Parameters:
  • file – Image file to open


void gs_texture_destroy(gs_texture_t *tex)

Destroys a texture

Parameters:
  • tex – Texture object


uint32_t gs_texture_get_width(const gs_texture_t *tex)

Gets the texture’s width

Parameters:
  • tex – Texture object

Returns:

The texture’s width


uint32_t gs_texture_get_height(const gs_texture_t *tex)

Gets the texture’s height

Parameters:
  • tex – Texture object

Returns:

The texture’s height


enum gs_color_format gs_texture_get_color_format(const gs_texture_t *tex)

Gets the texture’s color format

Parameters:
  • tex – Texture object

Returns:

The texture’s color format


bool gs_texture_map(gs_texture_t *tex, uint8_t **ptr, uint32_t *linesize)

Maps a texture.

Parameters:
  • tex – Texture object

  • ptr – Pointer to receive the pointer to the texture data to write to

  • linesize – Pointer to receive the line size (pitch) of the texture


void gs_texture_unmap(gs_texture_t *tex)

Unmaps a texture.

Parameters:
  • tex – Texture object


void gs_texture_set_image(gs_texture_t *tex, const uint8_t *data, uint32_t linesize, bool invert)

Sets the image of a dynamic texture

Parameters:
  • tex – Texture object

  • data – Data to set as the image

  • linesize – Line size (pitch) of the data

  • inverttrue to invert vertically, false otherwise


gs_texture_t *gs_texture_create_from_dmabuf(unsigned int width, unsigned int height, uint32_t drm_format, enum gs_color_format color_format, uint32_t n_planes, const int *fds, const uint32_t *strides, const uint32_t *offsets, const uint64_t *modifiers)

only Linux, FreeBSD, DragonFly: Creates a texture from DMA-BUF metadata.

Exchanging DMA-BUFs is a verbose process because of its multiplanar nature. For example, YUV can have each plane as a color channel, or a monitor buffer can have the cursor stored in a separate plane.

This function treats the OBS Studio format and the DRM format separately. This allows creating textures from DMA-BUFs with unsupported formats (e.g. YUV) and perform the color format conversion using shaders. However, be careful to always try and match the formats correctly, otherwise textures can fail to be created or rendered.

All modifiers passed in the modifiers array must be equal. Passing different modifiers for each plane is unsupported.

Parameters:
  • width – Width of the texture

  • height – Height of the texture

  • drm_format – DRM format of the DMA-BUF buffer

  • color_format – Color format compatible with OBS Studio

  • n_planes – Number of planes of the DMA-BUF

  • fds – Array of size n_planes with the file descriptor of each plane

  • strides – Array of size n_planes with the stride of each plane

  • offsets – Array of size n_planes with the offset of each plane

  • modifiers – Array of size n_planes with the modifier of each plane

Returns:

A texture object on success, or NULL on failure

Return type:

gs_texture_t*


enum gs_dmabuf_flags

DMA-BUF capabilities:

  • GS_DMABUF_FLAG_NONE

  • GS_DMABUF_FLAG_SUPPORTS_IMPLICIT_MODIFIERS - Renderer supports implicit modifiers


bool *gs_query_dmabuf_capabilities(enum gs_dmabuf_flags *dmabuf_flags, uint32_t **drm_formats, size_t *n_formats)

only Linux, FreeBSD, DragonFly: Queries the capabilities for DMA-BUFs.

Graphics cards can optimize frame buffers by storing them in custom layouts, depending on their hardware features. These layouts can make these frame buffers unsuitable for linear processing. This function allows querying whether the graphics card in use supports implicit modifiers, and the supported texture formats.

The caller must free the drm_formats array with bfree() after use.

Parameters:
  • dmabuf_flags – Pointer to receive a capability bitmap

  • drm_formats – Pointer to receive an array of DRM formats

  • n_formats – Pointer to receive the number of formats

Return type:

bool


bool *gs_query_dmabuf_modifiers_for_format(uint32_t drm_format, uint64_t **modifiers, size_t *n_modifiers)

only Linux, FreeBSD, DragonFly: Queries the supported DMA-BUF modifiers for a given format.

This function queries all supported explicit modifiers for a format, stores them as an array and returns the number of supported modifiers.

The caller must free the modifiers array with bfree() after use.

Parameters:
  • drm_format – DRM format of the DMA-BUF buffer

  • modifiers – Pointer to receive an array of modifiers

  • n_modifiers – Pointer to receive the number of modifiers

Return type:

bool


gs_texture_t *gs_texture_create_from_iosurface(void *iosurf)

macOS only: Creates a texture from an IOSurface.

Parameters:
  • iosurf – IOSurface object


bool gs_texture_rebind_iosurface(gs_texture_t *texture, void *iosurf)

macOS only: Rebinds a texture to another IOSurface

Parameters:
  • texture – Texture object

  • iosuf – IOSurface object


gs_texture_t *gs_texture_create_gdi(uint32_t width, uint32_t height)

Windows only: Creates a GDI-interop texture

Parameters:
  • width – Width

  • height – Height


void *gs_texture_get_dc(gs_texture_t *gdi_tex)

Windows only: Gets the HDC of a GDI-interop texture. Call gs_texture_release_dc() to release the HDC.

Parameters:
  • gdi_tex – GDI-interop texture object

Returns:

HDC object


void gs_texture_release_dc(gs_texture_t *gdi_tex)

Windows only: Releases the HDC of the GDI-interop texture.

Parameters:
  • gdi_tex – GDI-interop texture object


gs_texture_t *gs_texture_open_shared(uint32_t handle)

Windows only: Creates a texture from a shared texture handle.

Parameters:
  • handle – Shared texture handle

Returns:

A texture object


bool gs_gdi_texture_available(void)

Windows only: Returns whether GDI-interop textures are available.

Returns:

true if available, false otherwise


bool gs_shared_texture_available(void)

Windows only: Returns whether shared textures are available.

Returns:

true if available, false otherwise


Cube Texture Functions

gs_texture_t *gs_cubetexture_create(uint32_t size, enum gs_color_format color_format, uint32_t levels, const uint8_t **data, uint32_t flags)

Creates a cubemap texture.

Parameters:
  • size – Width/height/depth value

  • color_format – Color format

  • levels – Number of texture levels

  • data – Pointer to array of texture data pointers

  • flags

    Can be 0 or a bitwise-OR combination of one or more of the following value:

    • GS_BUILD_MIPMAPS - Automatically builds mipmaps (Note: not fully tested)

    • GS_DYNAMIC - Dynamic

    • GS_RENDER_TARGET - Render target

Returns:

A new cube texture object


void gs_cubetexture_destroy(gs_texture_t *cubetex)

Destroys a cube texture.

Parameters:
  • cubetex – Cube texture object


uint32_t gs_cubetexture_get_size(const gs_texture_t *cubetex)

Get the width/height/depth value of a cube texture.

Parameters:
  • cubetex – Cube texture object

Returns:

The width/height/depth value of the cube texture


enum gs_color_format gs_cubetexture_get_color_format(const gs_texture_t *cubetex)

Gets the color format of a cube texture.

Parameters:
  • cubetex – Cube texture object

Returns:

The color format of the cube texture


void gs_cubetexture_set_image(gs_texture_t *cubetex, uint32_t side, const void *data, uint32_t linesize, bool invert)

Sets an image of a cube texture side.

Parameters:
  • cubetex – Cube texture object

  • side – Side

  • data – Texture data to set

  • linesize – Line size (pitch) of the texture data

  • inverttrue to invert texture data, false otherwise


Staging Surface Functions

Staging surfaces are used to efficiently copy textures from VRAM to RAM.

gs_stagesurf_t *gs_stagesurface_create(uint32_t width, uint32_t height, enum gs_color_format color_format)

Creates a staging surface.

Parameters:
  • width – Width

  • height – Height

  • color_format – Color format

Returns:

The staging surface object


void gs_stagesurface_destroy(gs_stagesurf_t *stagesurf)

Destroys a staging surface.

Parameters:
  • stagesurf – Staging surface object


uint32_t gs_stagesurface_get_width(const gs_stagesurf_t *stagesurf)
uint32_t gs_stagesurface_get_height(const gs_stagesurf_t *stagesurf)

Gets the width/height of a staging surface object.

Parameters:
  • stagesurf – Staging surface object

Returns:

Width/height of the staging surface


enum gs_color_format gs_stagesurface_get_color_format(const gs_stagesurf_t *stagesurf)

Gets the color format of a staging surface object.

Parameters:
  • stagesurf – Staging surface object

Returns:

Color format of the staging surface


bool gs_stagesurface_map(gs_stagesurf_t *stagesurf, uint8_t **data, uint32_t *linesize)

Maps the staging surface texture (for reading). Call gs_stagesurface_unmap() to unmap when complete.

Parameters:
  • stagesurf – Staging surface object

  • data – Pointer to receive texture data pointer

  • linesize – Pointer to receive line size (pitch) of the texture data

Returns:

true if map successful, false otherwise


void gs_stagesurface_unmap(gs_stagesurf_t *stagesurf)

Unmaps a staging surface.

Parameters:
  • stagesurf – Staging surface object


Z-Stencil Functions

gs_zstencil_t *gs_zstencil_create(uint32_t width, uint32_t height, enum gs_zstencil_format format)

Creates a Z-stencil surface object.

Parameters:
  • width – Width

  • height – Height

  • format – Format

Returns:

New Z-stencil surface object, or NULL if failed


void gs_zstencil_destroy(gs_zstencil_t *zstencil)

Destroys a Z-stencil buffer.

Parameters:
  • zstencil – Z-stencil surface object


Sampler State Functions

gs_samplerstate_t *gs_samplerstate_create(const struct gs_sampler_info *info)

Creates a sampler state object.

Parameters:
  • info – Sampler state information

Returns:

New sampler state object


void gs_samplerstate_destroy(gs_samplerstate_t *samplerstate)

Destroys a sampler state object.

Parameters:
  • samplerstate – Sampler state object


Vertex Buffer Functions

gs_vertbuffer_t *gs_vertexbuffer_create(struct gs_vb_data *data, uint32_t flags)

Creates a vertex buffer.

Parameters:
  • data – Vertex buffer data to create vertex buffer with. The structure should be created with gs_vbdata_create(), and then buffers in this structure should be allocated with bmalloc(), bzalloc(), or brealloc(). The ownership of the gs_vb_data pointer is then passed to the function, and they should not be destroyed by the caller once passed

  • flags

    Creation flags. Can be 0 or a bitwise-OR combination of any of the following values:

    • GS_DYNAMIC - Can be dynamically updated in real time.

    • GS_DUP_BUFFER - Do not pass buffer ownership of the structure or the buffer pointers within the structure.

Returns:

A new vertex buffer object, or NULL if failed


void gs_vertexbuffer_destroy(gs_vertbuffer_t *vertbuffer)

Destroys a vertex buffer object.

Parameters:
  • vertbuffer – Vertex buffer object


void gs_vertexbuffer_flush(gs_vertbuffer_t *vertbuffer)

Flushes a vertex buffer to its interval vertex data object. To modify its internal vertex data, call gs_vertexbuffer_get_data().

Can only be used with dynamic vertex buffer objects.

Parameters:
  • vertbuffer – Vertex buffer object


void gs_vertexbuffer_flush_direct(gs_vertbuffer_t *vertbuffer, const struct gs_vb_data *data)

Directly flushes a vertex buffer to the specified vertex buffer data. .

Can only be used with dynamic vertex buffer objects.

Parameters:
  • vertbuffer – Vertex buffer object

  • data – Vertex buffer data to flush. Components that don’t need to be flushed can be left NULL


struct gs_vb_data *gs_vertexbuffer_get_data(const gs_vertbuffer_t *vertbuffer)

Gets the vertex buffer data associated with a vertex buffer object. This data can be changed and vertex buffer can be updated with gs_vertexbuffer_flush().

Can only be used with dynamic vertex buffer objects.

Parameters:
  • vertbuffer – Vertex buffer object

Returns:

Vertex buffer data structure


Index Buffer Functions

gs_indexbuffer_t *gs_indexbuffer_create(enum gs_index_type type, void *indices, size_t num, uint32_t flags)

Creates an index buffer.

Parameters:
  • type – Index buffer type

  • indices – Index buffer data. This buffer must be allocated with bmalloc(), bzalloc(), or bralloc(), and ownership of this buffer is passed to the index buffer object.

  • num – Number of indices in the buffer

  • flags

    Creation flags. Can be 0 or a bitwise-OR combination of any of the following values:

    • GS_DYNAMIC - Can be dynamically updated in real time.

    • GS_DUP_BUFFER - Do not pass buffer ownership

Returns:

A new index buffer object, or NULL if failed


void gs_indexbuffer_destroy(gs_indexbuffer_t *indexbuffer)

Destroys an index buffer object.

Parameters:
  • indexbuffer – Index buffer object


void gs_indexbuffer_flush(gs_indexbuffer_t *indexbuffer)

Flushes a index buffer to its interval index data object. To modify its internal index data, call gs_indexbuffer_get_data().

Can only be used with dynamic index buffer objects.

Parameters:
  • indexbuffer – Index buffer object


void gs_indexbuffer_flush_direct(gs_indexbuffer_t *indexbuffer, const void *data)

Flushes a index buffer to the specified index buffer data.

Can only be used with dynamic index buffer objects.

Parameters:
  • indexbuffer – Index buffer object

  • data – Index buffer data to flush


void *gs_indexbuffer_get_data(const gs_indexbuffer_t *indexbuffer)

Gets the index buffer data associated with a index buffer object. This data can be changed and index buffer can be updated with gs_indexbuffer_flush().

Can only be used with dynamic index buffer objects.

Parameters:
  • vertbuffer – Index buffer object

Returns:

Index buffer data pointer


size_t gs_indexbuffer_get_num_indices(const gs_indexbuffer_t *indexbuffer)

Gets the number of indices associated with this index buffer.

Parameters:
  • indexbuffer – Index buffer object

Returns:

Number of indices the vertex buffer object has


enum gs_index_type gs_indexbuffer_get_type(const gs_indexbuffer_t *indexbuffer)

Gets the type of index buffer.

Parameters:
  • indexbuffer – Index buffer object

Returns:

Index buffer type


Display Duplicator (Windows Only)

gs_duplicator_t *gs_duplicator_create(int monitor_idx)

void gs_duplicator_destroy(gs_duplicator_t *duplicator)

bool gs_duplicator_update_frame(gs_duplicator_t *duplicator)

gs_texture_t *gs_duplicator_get_texture(gs_duplicator_t *duplicator)

bool gs_get_duplicator_monitor_info(int monitor_idx, struct gs_monitor_info *monitor_info)

Monitor Functions

bool gs_is_monitor_hdr(void *monitor)

Render Helper Functions

void gs_render_start(bool b_new)

void gs_render_stop(enum gs_draw_mode mode)

gs_vertbuffer_t *gs_render_save(void)

void gs_vertex2f(float x, float y)

void gs_vertex3f(float x, float y, float z)

void gs_normal3f(float x, float y, float z)

void gs_color(uint32_t color)

void gs_texcoord(float x, float y, int unit)

void gs_vertex2v(const struct vec2 *v)

void gs_vertex3v(const struct vec3 *v)

void gs_normal3v(const struct vec3 *v)

void gs_color4v(const struct vec4 *v)

void gs_texcoord2v(const struct vec2 *v, int unit)

Graphics Types

typedef struct gs_duplicator gs_duplicator_t
typedef struct gs_texture gs_texture_t
typedef struct gs_stage_surface gs_stagesurf_t
typedef struct gs_zstencil_buffer gs_zstencil_t
typedef struct gs_vertex_buffer gs_vertbuffer_t
typedef struct gs_index_buffer gs_indexbuffer_t
typedef struct gs_sampler_state gs_samplerstate_t
typedef struct gs_swap_chain gs_swapchain_t
typedef struct gs_texture_render gs_texrender_t
typedef struct gs_shader gs_shader_t
typedef struct gs_shader_param gs_sparam_t
typedef struct gs_device gs_device_t
typedef struct graphics_subsystem graphics_t