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:

  • enable – true to enable, false to disable

void gs_enable_depth_test(bool enable)

Enables/disables depth testing

Parameters:

  • enable – true to enable, false to disable

void gs_enable_stencil_test(bool enable)

Enables/disables stencil testing

Parameters:

  • enable – true to enable, false to disable

void gs_enable_stencil_write(bool enable)

Enables/disables stencil writing

Parameters:

  • enable – true to enable, false to disable

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

Enables/disables specific color channels

Parameters:

  • red – true to enable red channel, false to disable

  • green – true to enable green channel, false to disable

  • blue – true to enable blue channel, false to disable

  • alpha – true 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

  • invert – true 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

  • invert – true 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