obs-studio/docs/sphinx/reference-libobs-graphics-graphics.rst

Core Graphics API
=================

.. code:: cpp

   #include <graphics/graphics.h>


Graphics Enumerations
---------------------

.. type:: 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

.. type:: 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

.. type:: 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

.. type:: 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

.. type:: 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

.. type:: 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

.. type:: 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

.. type:: enum gs_stencil_side

   Stencil side.  Can be one of the following values:

   - GS_STENCIL_FRONT=1
   - GS_STENCIL_BACK
   - GS_STENCIL_BOTH

.. type:: 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

.. type:: 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

.. type:: 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

.. type:: 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

.. type:: enum gs_texture_type

   Texture type.  Can be one of the following values:

   - GS_TEXTURE_2D
   - GS_TEXTURE_3D
   - GS_TEXTURE_CUBE


Graphics Structures
-------------------

.. type:: struct gs_monitor_info
.. member:: int gs_monitor_info.rotation_degrees
.. member:: long gs_monitor_info.x
.. member:: long gs_monitor_info.y
.. member:: long gs_monitor_info.cx
.. member:: long gs_monitor_info.cy

---------------------

.. type:: struct gs_tvertarray
.. member:: size_t gs_tvertarray.width
.. member:: void *gs_tvertarray.array

---------------------

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

---------------------

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

---------------------

.. type:: struct gs_display_mode
.. member:: uint32_t gs_display_mode.width
.. member:: uint32_t gs_display_mode.height
.. member:: uint32_t gs_display_mode.bits
.. member:: uint32_t gs_display_mode.freq

---------------------

.. type:: struct gs_rect
.. member:: int gs_rect.x
.. member:: int gs_rect.y
.. member:: int gs_rect.cx
.. member:: int gs_rect.cy

---------------------

.. type:: struct gs_window

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

.. member:: void                    *gs_window.hwnd

   (Windows only) an HWND widget.

.. member:: id  gs_window.view

   (Mac only) A view ID.

.. member:: uint32_t gs_window.id
            void* gs_window.display

   (Linux only) Window ID and display

---------------------

.. type:: struct gs_init_data

   Swap chain initialization data.

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

---------------------


Initialization Functions
------------------------

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

   Enumerates adapters (this really only applies on windows).

   :param callback: Enumeration callback
   :param param:    Private data passed to the callback

---------------------

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

   Creates a graphics context

   :param graphics: Pointer to receive the graphics context
   :param module:   Module name
   :param adapter:  Adapter index
   :return:         Can return one of the following values:

                    - GS_SUCCESS
                    - GS_ERROR_FAIL
                    - GS_ERROR_MODULE_NOT_FOUND
                    - GS_ERROR_NOT_SUPPORTED

---------------------

.. function:: void gs_destroy(graphics_t *graphics)

   Destroys a graphics context

   :param graphics: Graphics context

---------------------

.. function:: void gs_enter_context(graphics_t *graphics)

   Enters and locks the graphics context

   :param graphics: Graphics context

---------------------

.. function:: void gs_leave_context(void)

   Leaves and unlocks the graphics context

   :param graphics: Graphics context

---------------------

.. function:: graphics_t *gs_get_context(void)

   :return: The currently locked graphics context for this thread

---------------------


Matrix Stack Functions
----------------------

.. function:: void gs_matrix_push(void)

   Pushes the matrix stack and duplicates the current matrix.

---------------------

.. function:: void gs_matrix_pop(void)

   Pops the current matrix from the matrix stack.

---------------------

.. function:: void gs_matrix_identity(void)

   Sets the current matrix to an identity matrix.

---------------------

.. function:: void gs_matrix_transpose(void)

   Transposes the current matrix.

---------------------

.. function:: void gs_matrix_set(const struct matrix4 *matrix)

   Sets the current matrix.

   :param matrix: The matrix to set

---------------------

.. function:: void gs_matrix_get(struct matrix4 *dst)

   Gets the current matrix

   :param dst: Destination matrix

---------------------

.. function:: void gs_matrix_mul(const struct matrix4 *matrix)

   Multiplies the current matrix

   :param matrix: Matrix to multiply the current stack matrix with

---------------------

.. function:: void gs_matrix_rotquat(const struct quat *rot)

   Multiplies the current matrix with a quaternion

   :param rot: Quaternion to multiple the current matrix stack with

---------------------

.. function:: 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

   :param rot: Axis angle to multiple the current matrix stack with

---------------------

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

   Translates the current matrix

   :param pos: Vector to translate the current matrix stack with

---------------------

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

   Scales the current matrix

   :param scale: Scale value to scale the current matrix stack with

---------------------


Draw Functions
--------------

.. function:: gs_effect_t *gs_get_effect(void)

   :return: The currently active effect, or *NULL* if none active

---------------------

.. function:: 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.

   :param tex:    Texture to draw
   :param 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

   :param width:  Width
   :param height: Height

---------------------

.. function:: 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.

   :param tex:    Texture to draw
   :param 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

   :param x:      X value within subregion
   :param y:      Y value within subregion
   :param cx:     CX value of subregion
   :param cy:     CY value of subregion

---------------------

.. function:: void gs_reset_viewport(void)

    Sets the viewport to current swap chain size

---------------------

.. function:: void gs_set_2d_mode(void)

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

---------------------

.. function:: void gs_set_3d_mode(double fovy, double znear, double zfar)

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

    :param fovy:  Field of view (in degrees)
    :param znear: Near plane
    :param zfar:  Far plane

---------------------

.. function:: void gs_viewport_push(void)

   Pushes/stores the current viewport

---------------------

.. function:: void gs_viewport_pop(void)

   Pops/recalls the last pushed viewport

---------------------

.. function:: void gs_perspective(float fovy, float aspect, float znear, float zfar)

   Sets the projection matrix to a perspective mode

   :param fovy:   Field of view (in degrees)
   :param aspect: Aspect ratio
   :param znear:  Near plane
   :param zfar:   Far plane

---------------------

.. function:: void gs_blend_state_push(void)

   Pushes/stores the current blend state

---------------------

.. function:: void gs_blend_state_pop(void)

   Pops/restores the last blend state

---------------------

.. function:: void gs_reset_blend_state(void)

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

---------------------


Swap Chains
-----------

.. function:: gs_swapchain_t *gs_swapchain_create(const struct gs_init_data *data)

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

   :param data: Swap chain initialization data
   :return:     New swap chain object, or *NULL* if failed

---------------------

.. function:: void     gs_swapchain_destroy(gs_swapchain_t *swapchain)

   Destroys a swap chain

---------------------

.. function:: void gs_resize(uint32_t cx, uint32_t cy)

   Resizes the currently active swap chain

   :param cx: New width
   :param cy: New height

---------------------

.. function:: void gs_get_size(uint32_t *cx, uint32_t *cy)

   Gets the size of the currently active swap chain

   :param cx: Pointer to receive width
   :param cy: Pointer to receive height

---------------------

.. function:: uint32_t gs_get_width(void)

   Gets the width of the currently active swap chain

---------------------

.. function:: uint32_t gs_get_height(void)

   Gets the height of the currently active swap chain

---------------------


Resource Loading
----------------

.. function:: void gs_load_vertexbuffer(gs_vertbuffer_t *vertbuffer)

   Loads a vertex buffer

   :param vertbuffer: Vertex buffer to load, or NULL to unload

---------------------

.. function:: void gs_load_indexbuffer(gs_indexbuffer_t *indexbuffer)

   Loads a index buffer

   :param indexbuffer: Index buffer to load, or NULL to unload

---------------------

.. function:: void gs_load_texture(gs_texture_t *tex, int unit)

   Loads a texture (this is usually not called manually)

   :param tex:  Texture to load, or NULL to unload
   :param unit: Texture unit to load texture for

---------------------

.. function:: void gs_load_samplerstate(gs_samplerstate_t *samplerstate, int unit)

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

   :param samplerstate: Sampler state to load, or NULL to unload
   :param unit:         Texture unit to load sampler state for

---------------------

.. function:: void gs_load_swapchain(gs_swapchain_t *swapchain)

   Loads a swapchain

   :param swapchain: Swap chain to load, or NULL to unload

---------------------


Draw Functions
--------------

.. function:: gs_texture_t  *gs_get_render_target(void)

   :return: The currently active render target

---------------------

.. function:: gs_zstencil_t *gs_get_zstencil_target(void)

   :return: The currently active Z-stencil target

---------------------

.. function:: void gs_set_render_target(gs_texture_t *tex, gs_zstencil_t *zstencil)

   Sets the active render target

   :param tex:      Texture to set as the active render target
   :param zstencil: Z-stencil to use as the active render target

---------------------

.. function:: 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

   :param cubetex:  Cubemap
   :param side:     Cubemap side
   :param zstencil: Z-stencil buffer, or *NULL* if none

---------------------

.. function:: void gs_copy_texture(gs_texture_t *dst, gs_texture_t *src)

   Copies a texture

   :param dst: Destination texture
   :param src: Source texture

---------------------

.. function:: 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.

   :param dst: Staging surface
   :param src: Texture to stage

---------------------

.. function:: 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).

---------------------

.. function:: void gs_draw(enum gs_draw_mode draw_mode, uint32_t start_vert, uint32_t num_verts)

   Draws a primitive or set of primitives.

   :param draw_mode:  The primitive draw mode to use
   :param start_vert: Starting vertex index
   :param num_verts:  Number of vertices

---------------------

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

   Clears color/depth/stencil buffers.

   :param 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

   :param color:       Color value to clear the color buffer with
   :param depth:       Depth value to clear the depth buffer with
   :param stencil:     Stencil value to clear the stencil buffer with

---------------------

.. function:: void gs_present(void)

   Displays what was rendered on to the current render target

---------------------

.. function:: void gs_flush(void)

   Flushes GPU calls

---------------------

.. function:: void gs_set_cull_mode(enum gs_cull_mode mode)

   Sets the current cull mode.

   :param mode: Cull mode

---------------------

.. function:: enum gs_cull_mode gs_get_cull_mode(void)

   :return: The current cull mode

---------------------

.. function:: void gs_enable_blending(bool enable)

   Enables/disables blending

   :param enable: *true* to enable, *false* to disable

---------------------

.. function:: void gs_enable_depth_test(bool enable)

   Enables/disables depth testing

   :param enable: *true* to enable, *false* to disable

---------------------

.. function:: void gs_enable_stencil_test(bool enable)

   Enables/disables stencil testing

   :param enable: *true* to enable, *false* to disable

---------------------

.. function:: void gs_enable_stencil_write(bool enable)

   Enables/disables stencil writing

   :param enable: *true* to enable, *false* to disable

---------------------

.. function:: void gs_enable_color(bool red, bool green, bool blue, bool alpha)

   Enables/disables specific color channels

   :param red:   *true* to enable red channel, *false* to disable
   :param green: *true* to enable green channel, *false* to disable
   :param blue:  *true* to enable blue channel, *false* to disable
   :param alpha: *true* to enable alpha channel, *false* to disable

---------------------

.. function:: void gs_blend_function(enum gs_blend_type src, enum gs_blend_type dest)

   Sets the blend function

   :param src:  Blend type for the source
   :param dest: Blend type for the destination

---------------------

.. function:: 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 for RGB and alpha separately

   :param src_c:  Blend type for the source RGB
   :param dest_c: Blend type for the destination RGB
   :param src_a:  Blend type for the source alpha
   :param dest_a: Blend type for the destination alpha

---------------------

.. function:: void gs_depth_function(enum gs_depth_test test)

   Sets the depth function

   :param test: Sets the depth test type

---------------------

.. function:: void gs_stencil_function(enum gs_stencil_side side, enum gs_depth_test test)

   Sets the stencil function

   :param side: Stencil side
   :param test: Depth test

---------------------

.. function:: 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

   :param side:  Stencil side
   :param fail:  Operation to perform on stencil test failure
   :param zfail: Operation to perform on depth test failure
   :param zpass: Operation to perform on depth test success

---------------------

.. function:: void gs_set_viewport(int x, int y, int width, int height)

   Sets the current viewport

   :param x:      X position relative to upper left
   :param y:      Y position relative to upper left
   :param width:  Width of the viewport
   :param height: Height of the viewport

---------------------

.. function:: void gs_get_viewport(struct gs_rect *rect)

   Gets the current viewport

   :param rect: Pointer to recieve viewport rectangle

---------------------

.. function:: void gs_set_scissor_rect(const struct gs_rect *rect)

   Sets or clears the current scissor rectangle

   :rect: Scissor rectangle, or *NULL* to clear

---------------------

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

   Sets the projection matrix to an orthographic matrix

---------------------

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

   Sets the projection matrix to a frustum matrix

---------------------

.. function:: void gs_projection_push(void)

   Pushes/stores the current projection matrix

---------------------

.. function:: void gs_projection_pop(void)

   Pops/restores the last projection matrix pushed

---------------------


Texture Functions
-----------------

.. function:: 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.

   :param width:        Width
   :param height:       Height
   :param color_format: Color format
   :param levels:       Number of total texture levels.  Set to 1 if no
                        mip-mapping
   :param data:         Pointer to array of texture data pointers
   :param 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

   :return:             A new texture object

---------------------

.. function:: 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 :ref:`image_file_helper`.

   :param file: Image file to open

---------------------

.. function:: void     gs_texture_destroy(gs_texture_t *tex)

   Destroys a texture

   :param tex: Texture object

---------------------

.. function:: uint32_t gs_texture_get_width(const gs_texture_t *tex)

   Gets the texture's width

   :param tex: Texture object
   :return:    The texture's width

---------------------

.. function:: uint32_t gs_texture_get_height(const gs_texture_t *tex)

   Gets the texture's height

   :param tex: Texture object
   :return:    The texture's height

---------------------

.. function:: enum gs_color_format gs_texture_get_color_format(const gs_texture_t *tex)

   Gets the texture's color format

   :param tex: Texture object
   :return:    The texture's color format

---------------------

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

   Maps a texture.

   :param tex:      Texture object
   :param ptr:      Pointer to receive the pointer to the texture data
                    to write to
   :param linesize: Pointer to receive the line size (pitch) of the
                    texture

---------------------

.. function:: void     gs_texture_unmap(gs_texture_t *tex)

   Unmaps a texture.

   :param tex: Texture object

---------------------

.. function:: 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

   :param tex:      Texture object
   :param data:     Data to set as the image
   :param linesize: Line size (pitch) of the data
   :param invert:   *true* to invert vertically, *false* otherwise

---------------------

.. function:: gs_texture_t *gs_texture_create_from_iosurface(void *iosurf)

   **Mac only:** Creates a texture from an IOSurface.

   :param iosurf: IOSurface object

---------------------

.. function:: bool     gs_texture_rebind_iosurface(gs_texture_t *texture, void *iosurf)

   **Mac only:** Rebinds a texture to another IOSurface

   :param texture: Texture object
   :param iosuf:   IOSurface object

---------------------

.. function:: gs_texture_t *gs_texture_create_gdi(uint32_t width, uint32_t height)

   **Windows only:** Creates a GDI-interop texture

   :param width:  Width
   :param height: Height

---------------------

.. function:: void *gs_texture_get_dc(gs_texture_t *gdi_tex)

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

   :param gdi_tex: GDI-interop texture object
   :return:        HDC object

---------------------

.. function:: void gs_texture_release_dc(gs_texture_t *gdi_tex)

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

   :param gdi_tex: GDI-interop texture object

---------------------

.. function:: gs_texture_t *gs_texture_open_shared(uint32_t handle)

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

   :param handle: Shared texture handle
   :return:       A texture object

---------------------

.. function:: bool gs_gdi_texture_available(void)

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

   :return: *true* if available, *false* otherwise

---------------------

.. function:: bool gs_shared_texture_available(void)

   **Windows only:** Returns whether shared textures are available.

   :return: *true* if available, *false* otherwise

---------------------


Cube Texture Functions
----------------------

.. function:: 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.

   :param size:         Width/height/depth value
   :param color_format: Color format
   :param levels:       Number of texture levels
   :param data:         Pointer to array of texture data pointers
   :param 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

   :return:             A new cube texture object

---------------------

.. function:: void     gs_cubetexture_destroy(gs_texture_t *cubetex)

   Destroys a cube texture.

   :param cubetex: Cube texture object

---------------------

.. function:: uint32_t gs_cubetexture_get_size(const gs_texture_t *cubetex)

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

   :param cubetex: Cube texture object
   :return:        The width/height/depth value of the cube texture

---------------------

.. function:: enum gs_color_format gs_cubetexture_get_color_format(const gs_texture_t *cubetex)

   Gets the color format of a cube texture.

   :param cubetex: Cube texture object
   :return:        The color format of the cube texture

---------------------

.. function:: 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.

   :param cubetex:  Cube texture object
   :param side:     Side
   :param data:     Texture data to set
   :param linesize: Line size (pitch) of the texture data
   :param invert:   *true* to invert texture data, *false* otherwise

---------------------


Staging Surface Functions
-------------------------

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

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

   Creates a staging surface.

   :param width:        Width
   :param height:       Height
   :param color_format: Color format
   :return:             The staging surface object

---------------------

.. function:: void     gs_stagesurface_destroy(gs_stagesurf_t *stagesurf)

   Destroys a staging surface.

   :param stagesurf: Staging surface object

---------------------

.. function:: 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.

   :param stagesurf: Staging surface object
   :return:          Width/height of the staging surface

---------------------

.. function:: enum gs_color_format gs_stagesurface_get_color_format(const gs_stagesurf_t *stagesurf)

   Gets the color format of a staging surface object.

   :param stagesurf: Staging surface object
   :return:          Color format of the staging surface

---------------------

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

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

   :param stagesurf: Staging surface object
   :param data:      Pointer to receive texture data pointer
   :param linesize:  Pointer to receive line size (pitch) of the texture
                     data
   :return:          *true* if map successful, *false* otherwise

---------------------

.. function:: void     gs_stagesurface_unmap(gs_stagesurf_t *stagesurf)

   Unmaps a staging surface.

   :param stagesurf: Staging surface object

---------------------


Z-Stencil Functions
-------------------

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

   Creates a Z-stencil surface object.

   :param width:  Width
   :param height: Height
   :param format: Format
   :return:       New Z-stencil surface object, or *NULL* if failed

---------------------

.. function:: void     gs_zstencil_destroy(gs_zstencil_t *zstencil)

   Destroys a Z-stencil buffer.

   :param zstencil: Z-stencil surface object

---------------------


Sampler State Functions
-----------------------

.. function:: gs_samplerstate_t *gs_samplerstate_create(const struct gs_sampler_info *info)

   Creates a sampler state object.

   :param info: Sampler state information
   :return:     New sampler state object

---------------------

.. function:: void     gs_samplerstate_destroy(gs_samplerstate_t *samplerstate)

   Destroys a sampler state object.

   :param samplerstate: Sampler state object

---------------------


Vertex Buffer Functions
-----------------------

.. function:: gs_vertbuffer_t *gs_vertexbuffer_create(struct gs_vb_data *data, uint32_t flags)

   Creates a vertex buffer.

   :param 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 :c:func:`bmalloc()`, :c:func:`bzalloc()`, or
                 :c:func:`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

   :param 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.

   :return:      A new vertex buffer object, or *NULL* if failed

---------------------

.. function:: void     gs_vertexbuffer_destroy(gs_vertbuffer_t *vertbuffer)

   Destroys a vertex buffer object.

   :param vertbuffer: Vertex buffer object

---------------------

.. function:: 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
   :c:func:`gs_vertexbuffer_get_data()`.

   Can only be used with dynamic vertex buffer objects.

   :param vertbuffer: Vertex buffer object

---------------------

.. function:: 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.

   :param vertbuffer: Vertex buffer object
   :param data:       Vertex buffer data to flush.  Components that
                      don't need to be flushed can be left *NULL*

---------------------

.. function:: 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
   :c:func:`gs_vertexbuffer_flush()`.

   Can only be used with dynamic vertex buffer objects.

   :param vertbuffer: Vertex buffer object
   :return:           Vertex buffer data structure

---------------------


Index Buffer Functions
----------------------

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

   Creates an index buffer.

   :param type:    Index buffer type
   :param indices: Index buffer data.  This buffer must be allocated
                   with :c:func:`bmalloc()`, :c:func:`bzalloc()`, or
                   :c:func:`bralloc()`, and ownership of this buffer is
                   passed to the index buffer object.
   :param num:     Number of indices in the buffer

   :param 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

   :return:        A new index buffer object, or *NULL* if failed

---------------------

.. function:: void     gs_indexbuffer_destroy(gs_indexbuffer_t *indexbuffer)

   Destroys an index buffer object.

   :param indexbuffer: Index buffer object

---------------------

.. function:: 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 :c:func:`gs_indexbuffer_get_data()`.

   Can only be used with dynamic index buffer objects.

   :param indexbuffer: Index buffer object

---------------------

.. function:: 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.

   :param indexbuffer: Index buffer object
   :param data:        Index buffer data to flush

---------------------

.. function:: 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
   :c:func:`gs_indexbuffer_flush()`.

   Can only be used with dynamic index buffer objects.

   :param vertbuffer: Index buffer object
   :return:           Index buffer data pointer

---------------------

.. function:: size_t   gs_indexbuffer_get_num_indices(const gs_indexbuffer_t *indexbuffer)

   Gets the number of indices associated with this index buffer.

   :param indexbuffer: Index buffer object
   :return:            Number of indices the vertex buffer object has

---------------------

.. function:: enum gs_index_type gs_indexbuffer_get_type(const gs_indexbuffer_t *indexbuffer)

   Gets the type of index buffer.

   :param indexbuffer: Index buffer object
   :return:            Index buffer type

---------------------


Display Duplicator (Windows Only)
---------------------------------

.. function:: gs_duplicator_t *gs_duplicator_create(int monitor_idx)

---------------------

.. function:: void gs_duplicator_destroy(gs_duplicator_t *duplicator)

---------------------

.. function:: bool gs_duplicator_update_frame(gs_duplicator_t *duplicator)

---------------------

.. function:: gs_texture_t *gs_duplicator_get_texture(gs_duplicator_t *duplicator)

---------------------

.. function:: bool gs_get_duplicator_monitor_info(int monitor_idx, struct gs_monitor_info *monitor_info)

---------------------


Render Helper Functions
-----------------------

.. function:: void gs_render_start(bool b_new)

---------------------

.. function:: void gs_render_stop(enum gs_draw_mode mode)

---------------------

.. function:: gs_vertbuffer_t *gs_render_save(void)

---------------------

.. function:: void gs_vertex2f(float x, float y)

---------------------

.. function:: void gs_vertex3f(float x, float y, float z)

---------------------

.. function:: void gs_normal3f(float x, float y, float z)

---------------------

.. function:: void gs_color(uint32_t color)

---------------------

.. function:: void gs_texcoord(float x, float y, int unit)

---------------------

.. function:: void gs_vertex2v(const struct vec2 *v)

---------------------

.. function:: void gs_vertex3v(const struct vec3 *v)

---------------------

.. function:: void gs_normal3v(const struct vec3 *v)

---------------------

.. function:: void gs_color4v(const struct vec4 *v)

---------------------

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

---------------------


Graphics Types
--------------

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