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

docs/sphinx/reference-libobs-graphics-graphics.rst
1 695 строк47 KB
Lain
libobs/graphics: Add gs_draw_quadf()
23 апр 2025, 22:23
23 апр 2025, 22:23775ac56
Core Graphics API
=================

.. code:: cpp

   #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
.. 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

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

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

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

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

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

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

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

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

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

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

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

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

   (macOS only) A view ID.

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

   (Linux only) Window ID and display

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

.. 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. Can be omitted if drawing without
   a texture.

   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 (can be NULL if drawing without a
                  texture)
   :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_quadf(gs_texture_t *tex, uint32_t flip, float width, float height)

   Same as :c:func:`gs_draw_sprite()`, but with floating point width/height
   values instead of integer width/height values.

   :param tex:    Texture to draw (can be NULL if drawing without a
                  texture)
   :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_update_color_space(void)

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

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

.. 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:: enum gs_color_space gs_get_color_space(void)

   :return: The currently active color space

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

.. 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 with implicit GS_CS_SRGB color space

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

   :param tex:      Texture to set as the active render target
   :param zstencil: Z-stencil to use as the active render target
   :param space:    Color space of the 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's source and destination factors

   :param src:  Blend type for the blending equation's source factors
   :param dest: Blend type for the blending equation's destination factors

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

.. 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's source and destination factors for RGB and alpha separately

   :param src_c:  Blend type for the blending equation's source RGB factor
   :param dest_c: Blend type for the blending equation's destination RGB factor
   :param src_a:  Blend type for the blending equation's source alpha factor
   :param dest_a: Blend type for the blending equation's destination alpha factor

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

.. function:: void gs_blend_op(enum gs_blend_op_type op)

   Sets the blend function's operation type

   :param op: Operation type for the blending equation

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

.. 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 receive 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_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.

   :param width:        Width of the texture
   :param height:       Height of the texture
   :param drm_format:   DRM format of the DMA-BUF buffer
   :param color_format: Color format compatible with OBS Studio
   :param n_planes:     Number of planes of the DMA-BUF
   :param fds:          Array of size *n_planes* with the file descriptor of each plane
   :param strides:      Array of size *n_planes* with the stride of each plane
   :param offsets:      Array of size *n_planes* with the offset of each plane
   :param modifiers:    Array of size *n_planes* with the modifier of each plane
   :return:             A texture object on success, or *NULL* on failure
   :rtype:              gs_texture_t*

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

.. enum:: gs_dmabuf_flags

   DMA-BUF capabilities:

   - GS_DMABUF_FLAG_NONE
   - GS_DMABUF_FLAG_SUPPORTS_IMPLICIT_MODIFIERS  - Renderer supports implicit modifiers

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

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

   :param dmabuf_flags: Pointer to receive a capability bitmap
   :param drm_formats:  Pointer to receive an array of DRM formats
   :param n_formats:    Pointer to receive the number of formats
   :rtype:              bool

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

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

   :param drm_format:   DRM format of the DMA-BUF buffer
   :param modifiers:    Pointer to receive an array of modifiers
   :param n_modifiers:  Pointer to receive the number of modifiers
   :rtype:              bool

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

.. function:: bool gs_query_sync_capabilities(void)

   **only Linux, FreeBSD, DragonFly:** Checks if the use of synchronization objects is supported

   :rtype:  bool
   :return: *true* if supported, *false* otherwise

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

.. function:: gs_sync_t *gs_sync_create(void)

   **only Linux, FreeBSD, DragonFly:** Creates a synchronization object

   Inserts a fence command into the command stream of the bound context and
   creates a synchronization object that is signalled when all the commands
   preceding the inserted fence are executed.

   :rtype: gs_sync_t*

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

.. function:: gs_sync_t *gs_sync_create_from_syncobj_timeline_point(int syncobj_fd, uint64_t timeline_point)

   **only Linux, FreeBSD, DragonFly:** Creates a synchronization object

   Creates a synchronization object that is signalled when the specified
   timeline point of the given DRM syncobj is signalled.

   :param syncobj_fd:     A file descriptor that is referencing a DRM syncobj
   :param timeline_point: Timeline point of the DRM syncobj
   :rtype:                gs_sync_t*

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

.. function:: void gs_sync_destroy(gs_sync_t *sync)

   **only Linux, FreeBSD, DragonFly:** Destroys a synchronization object

   If the given synchronization object is in use, it will be marked for
   destruction and will be destroyed later when it is no longer referenced.

   :param sync: Synchronization object

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

.. function:: bool gs_sync_export_syncobj_timeline_point(gs_sync_t *sync, int syncobj_fd, uint64_t timeline_point)

   **only Linux, FreeBSD, DragonFly:** Exports a synchronization object to a DRM syncobj timeline point

   Creates a DRM syncobj timeline point that is signalled when the given
   synchronization object is signalled.

   :param sync:           Synchronization object
   :param syncobj_fd:     A file descriptor that is referencing a DRM syncobj
   :param timeline_point: Timeline point of the DRM syncobj
   :rtype:                bool
   :return:               *true* if the synchronization object is exported successfully, *false* otherwise

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

.. function:: bool gs_sync_signal_syncobj_timeline_point(int syncobj_fd, uint64_t timeline_point)

   **only Linux, FreeBSD, DragonFly:** Signals a DRM syncobj timeline point

   :param syncobj_fd:     A file descriptor that is referencing a DRM syncobj
   :param timeline_point: Timeline point of the DRM syncobj
   :rtype:                bool
   :return:               *true* if the timeline point is signalled successfully, *false* otherwise

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

.. function:: bool gs_sync_wait(gs_sync_t *sync)

   **only Linux, FreeBSD, DragonFly:** Wait for a synchronization object to be signalled

   Blocks the execution of the commands that would be inserted into the command
   stream of the bound context until the given synchronization object is
   signalled.

   :param sync: Synchronization object
   :rtype:      bool
   :return:     *true* if successful, *false* otherwise

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

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

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

   :param iosurf: IOSurface object

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

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

   **macOS 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)

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


Monitor Functions
---------------------------------

.. function:: bool gs_is_monitor_hdr(void *monitor)

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


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:: struct gs_duplicator       gs_duplicator_t
.. type:: struct gs_texture          gs_texture_t
.. type:: struct gs_stage_surface    gs_stagesurf_t
.. type:: struct gs_zstencil_buffer  gs_zstencil_t
.. type:: struct gs_vertex_buffer    gs_vertbuffer_t
.. type:: struct gs_index_buffer     gs_indexbuffer_t
.. type:: struct gs_sampler_state    gs_samplerstate_t
.. type:: struct gs_swap_chain       gs_swapchain_t
.. type:: struct gs_texture_render   gs_texrender_t
.. type:: struct gs_shader           gs_shader_t
.. type:: struct gs_shader_param     gs_sparam_t
.. type:: struct gs_device           gs_device_t
.. type:: void                       gs_sync_t
.. type:: struct graphics_subsystem  graphics_t