docs/sphinx/reference-libobs-graphics-effects.rst
Effects are a single collection of related shaders. They're used for easily writing vertex and pixel shaders together all in the same file in HLSL format.
.. code:: cpp
#include <graphics/graphics.h>
.. type:: struct gs_effect gs_effect_t
Effect object.
.. type:: struct gs_effect_technique gs_technique_t
Technique object.
.. type:: struct gs_effect_param gs_eparam_t
Effect parameter object.
.. function:: gs_effect_t *gs_effect_create_from_file(const char *file, char **error_string)
Creates an effect from file.
:param file: Path to the effect file
:param error_string: Receives a pointer to the error string, which
must be freed with :c:func:bfree(). If
NULL, this parameter is ignored.
:return: The effect object, or NULL on error
.. function:: gs_effect_t *gs_effect_create(const char *effect_string, const char *filename, char **error_string)
Creates an effect from a string.
:param effect_String: Effect string
:param error_string: Receives a pointer to the error string, which
must be freed with :c:func:bfree(). If
NULL, this parameter is ignored.
:return: The effect object, or NULL on error
.. function:: void gs_effect_destroy(gs_effect_t *effect)
Destroys the effect
:param effect: Effect object
.. function:: gs_technique_t *gs_effect_get_technique(const gs_effect_t *effect, const char *name)
Gets a technique of the effect.
:param effect: Effect object :param name: Name of the technique :return: Technique object, or NULL if not found
.. function:: gs_technique_t *gs_effect_get_current_technique(const gs_effect_t *effect)
Gets the current active technique of the effect.
:param effect: Effect object :return: Technique object, or NULL if none currently active
.. function:: size_t gs_technique_begin(gs_technique_t *technique)
Begins a technique.
:param technique: Technique object :return: Number of passes this technique uses
.. function:: void gs_technique_end(gs_technique_t *technique)
Ends a technique. Make sure all active passes have been ended before calling.
:param technique: Technique object
.. function:: bool gs_technique_begin_pass(gs_technique_t *technique, size_t pass)
Begins a pass. Automatically loads the vertex/pixel shaders associated with this pass. Draw after calling this function.
:param technique: Technique object :param pass: Pass index :return: true if the pass is valid, false otherwise
.. function:: bool gs_technique_begin_pass_by_name(gs_technique_t *technique, const char *name)
Begins a pass by its name if the pass has a name. Automatically loads the vertex/pixel shaders associated with this pass. Draw after calling this function.
:param technique: Technique object :param name: Name of the pass :return: true if the pass is valid, false otherwise
.. function:: void gs_technique_end_pass(gs_technique_t *technique)
Ends a pass.
:param technique: Technique object
.. function:: size_t gs_effect_get_num_params(const gs_effect_t *effect)
Gets the number of parameters associated with the effect.
:param effect: Effect object :return: Number of parameters the effect has
.. function:: gs_eparam_t *gs_effect_get_param_by_idx(const gs_effect_t *effect, size_t param)
Gets a parameter of an effect by its index.
:param effect: Effect object :param param: Parameter index :return: The effect parameter object, or NULL if index invalid
.. function:: gs_eparam_t *gs_effect_get_param_by_name(const gs_effect_t *effect, const char *name)
Gets parameter of an effect by its name.
:param effect: Effect object :param name: Name of the parameter :return: The effect parameter object, or NULL if not found
.. function:: size_t gs_param_get_num_annotations(const gs_eparam_t *param)
Gets the number of annotations associated with the parameter.
:param param: Param object :return: Number of annotations the param has
.. function:: gs_eparam_t *gs_param_get_annotation_by_idx(const gs_eparam_t *param, size_t annotation)
Gets an annotation of a param by its index.
:param param: Param object :param param: Annotation index :return: The effect parameter object (annotation), or NULL if index invalid
.. function:: gs_eparam_t *gs_param_get_annotation_by_name(const gs_eparam_t *param, const char *annotation)
Gets parameter of an effect by its name.
:param param: Param object :param name: Name of the annotation :return: The effect parameter object (annotation), or NULL if not found
.. function:: bool gs_effect_loop(gs_effect_t *effect, const char *name)
Helper function that automatically begins techniques/passes.
:param effect: Effect object :param name: Name of the technique to execute :return: true to draw, false when complete
Here is an example of how this function is typically used:
.. code:: cpp
for (gs_effect_loop(effect, "my_technique")) { /* perform drawing here */ [...] }
.. function:: gs_eparam_t *gs_effect_get_viewproj_matrix(const gs_effect_t *effect)
Gets the view/projection matrix parameter ("viewproj") of the effect.
:param effect: Effect object :return: The view/projection matrix parameter of the effect
.. function:: gs_eparam_t *gs_effect_get_world_matrix(const gs_effect_t *effect)
Gets the world matrix parameter ("world") of the effect.
:param effect: Effect object :return: The world matrix parameter of the effect
.. function:: void gs_effect_get_param_info(const gs_eparam_t *param, struct gs_effect_param_info *info)
Gets information about an effect parameter.
:param param: Effect parameter :param info: Pointer to receive the data
Relevant data types used with this function:
.. code:: cpp
enum gs_shader_param_type { GS_SHADER_PARAM_UNKNOWN, GS_SHADER_PARAM_BOOL, GS_SHADER_PARAM_FLOAT, GS_SHADER_PARAM_INT, GS_SHADER_PARAM_STRING, GS_SHADER_PARAM_VEC2, GS_SHADER_PARAM_VEC3, GS_SHADER_PARAM_VEC4, GS_SHADER_PARAM_INT2, GS_SHADER_PARAM_INT3, GS_SHADER_PARAM_INT4, GS_SHADER_PARAM_MATRIX4X4, GS_SHADER_PARAM_TEXTURE, };
struct gs_effect_param_info { const char *name; enum gs_shader_param_type type; }
.. function:: void gs_effect_set_bool(gs_eparam_t *param, bool val)
Sets a boolean parameter.
:param param: Effect parameter :param val: Boolean value
.. function:: void gs_effect_set_float(gs_eparam_t *param, float val)
Sets a floating point parameter.
:param param: Effect parameter :param val: Floating point value
.. function:: void gs_effect_set_int(gs_eparam_t *param, int val)
Sets a integer parameter.
:param param: Effect parameter :param val: Integer value
.. function:: void gs_effect_set_matrix4(gs_eparam_t *param, const struct matrix4 *val)
Sets a matrix parameter.
:param param: Effect parameter :param val: Matrix
.. function:: void gs_effect_set_vec2(gs_eparam_t *param, const struct vec2 *val)
Sets a 2-component vector parameter.
:param param: Effect parameter :param val: Vector
.. function:: void gs_effect_set_vec3(gs_eparam_t *param, const struct vec3 *val)
Sets a 3-component vector parameter.
:param param: Effect parameter :param val: Vector
.. function:: void gs_effect_set_vec4(gs_eparam_t *param, const struct vec4 *val)
Sets a 4-component vector parameter.
:param param: Effect parameter :param val: Vector
.. function:: void gs_effect_set_color(gs_eparam_t *param, uint32_t argb)
Convenience function for setting a color value via an integer value.
:param param: Effect parameter :param argb: Integer color value (i.e. hex value would be 0xAARRGGBB)
.. function:: void gs_effect_set_texture(gs_eparam_t *param, gs_texture_t *val)
Sets a texture parameter.
:param param: Effect parameter :param val: Texture
.. function:: void gs_effect_set_texture_srgb(gs_eparam_t *param, gs_texture_t *val)
Sets a texture parameter using SRGB view if available.
:param param: Effect parameter :param val: Texture
.. function:: void gs_effect_set_val(gs_eparam_t *param, const void *val, size_t size)
Sets a parameter with data manually.
:param param: Effect parameter :param val: Pointer to data :param size: Size of data
.. function:: void gs_effect_set_default(gs_eparam_t *param)
Sets the parameter to its default value
:param: Effect parameter
.. function:: void gs_effect_set_next_sampler(gs_eparam_t *param, gs_samplerstate_t *sampler)
Manually changes the sampler for an effect parameter the next time it's used.
:param param: Effect parameter :param sampler: Sampler state object
.. function:: void *gs_effect_get_val(gs_eparam_t *param)
Returns a copy of the param's current value.
:param param: Effect parameter
:return: A pointer to the copied byte value of the param's current value. Freed with :c:func:bfree().
.. function:: void gs_effect_get_default_val(gs_eparam_t *param)
Returns a copy of the param's default value.
:param param: Effect parameter
:return: A pointer to the copied byte value of the param's default value. Freed with :c:func:bfree().
.. function:: size_t gs_effect_get_val_size(gs_eparam_t *param)
Returns the size in bytes of the param's current value.
:param param: Effect parameter :return: The size in bytes of the param's current value.
.. function:: size_t gs_effect_get_default_val_size(gs_eparam_t *param)
Returns the size in bytes of the param's default value.
:param param: Effect parameter :return: The size in bytes of the param's default value.