Effects (Shaders)

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.

#include <graphics/graphics.h>
typedef struct gs_effect gs_effect_t

Effect object.

typedef struct gs_effect_technique gs_technique_t

Technique object.

typedef struct gs_effect_param gs_eparam_t

Effect parameter object.

gs_effect_t *gs_effect_create_from_file(const char *file, char **error_string)

Creates an effect from file.

Parameters:

  • file – Path to the effect file

  • error_string – Receives a pointer to the error string, which must be freed with bfree(). If NULL, this parameter is ignored.

Returns:

The effect object, or NULL on error

gs_effect_t *gs_effect_create(const char *effect_string, const char *filename, char **error_string)

Creates an effect from a string.

Parameters:

  • effect_String – Effect string

  • error_string – Receives a pointer to the error string, which must be freed with bfree(). If NULL, this parameter is ignored.

Returns:

The effect object, or NULL on error

void gs_effect_destroy(gs_effect_t *effect)

Destroys the effect

Parameters:

  • effect – Effect object

gs_technique_t *gs_effect_get_technique(const gs_effect_t *effect, const char *name)

Gets a technique of the effect.

Parameters:

  • effect – Effect object

  • name – Name of the technique

Returns:

Technique object, or NULL if not found

gs_technique_t *gs_effect_get_current_technique(const gs_effect_t *effect)

Gets the current active technique of the effect.

Parameters:

  • effect – Effect object

Returns:

Technique object, or NULL if none currently active

size_t gs_technique_begin(gs_technique_t *technique)

Begins a technique.

Parameters:

  • technique – Technique object

Returns:

Number of passes this technique uses

void gs_technique_end(gs_technique_t *technique)

Ends a technique. Make sure all active passes have been ended before calling.

Parameters:

  • technique – Technique object

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.

Parameters:

  • technique – Technique object

  • pass – Pass index

Returns:

true if the pass is valid, false otherwise

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.

Parameters:

  • technique – Technique object

  • name – Name of the pass

Returns:

true if the pass is valid, false otherwise

void gs_technique_end_pass(gs_technique_t *technique)

Ends a pass.

Parameters:

  • technique – Technique object

size_t gs_effect_get_num_params(const gs_effect_t *effect)

Gets the number of parameters associated with the effect.

Parameters:

  • effect – Effect object

Returns:

Number of parameters the effect has

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.

Parameters:

  • effect – Effect object

  • param – Parameter index

Returns:

The effect parameter object, or NULL if index invalid

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.

Parameters:

  • effect – Effect object

  • name – Name of the parameter

Returns:

The effect parameter object, or NULL if not found

size_t gs_param_get_num_annotations(const gs_eparam_t *param)

Gets the number of annotations associated with the parameter.

Parameters:

  • param – Param object

Returns:

Number of annotations the param has

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.

Parameters:

  • param – Param object

  • param – Annotation index

Returns:

The effect parameter object (annotation), or NULL if index invalid

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.

Parameters:

  • param – Param object

  • name – Name of the annotation

Returns:

The effect parameter object (annotation), or NULL if not found

bool gs_effect_loop(gs_effect_t *effect, const char *name)

Helper function that automatically begins techniques/passes.

Parameters:

  • effect – Effect object

  • name – Name of the technique to execute

Returns:

true to draw, false when complete

Here is an example of how this function is typically used:

for (gs_effect_loop(effect, "my_technique")) {
        /* perform drawing here */
        [...]
}
gs_eparam_t *gs_effect_get_viewproj_matrix(const gs_effect_t *effect)

Gets the view/projection matrix parameter (“viewproj”) of the effect.

Parameters:

  • effect – Effect object

Returns:

The view/projection matrix parameter of the effect

gs_eparam_t *gs_effect_get_world_matrix(const gs_effect_t *effect)

Gets the world matrix parameter (“world”) of the effect.

Parameters:

  • effect – Effect object

Returns:

The world matrix parameter of the effect

void gs_effect_get_param_info(const gs_eparam_t *param, struct gs_effect_param_info *info)

Gets information about an effect parameter.

Parameters:

  • param – Effect parameter

  • info – Pointer to receive the data

Relevant data types used with this function:

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;
}
void gs_effect_set_bool(gs_eparam_t *param, bool val)

Sets a boolean parameter.

Parameters:

  • param – Effect parameter

  • val – Boolean value

void gs_effect_set_float(gs_eparam_t *param, float val)

Sets a floating point parameter.

Parameters:

  • param – Effect parameter

  • val – Floating point value

void gs_effect_set_int(gs_eparam_t *param, int val)

Sets a integer parameter.

Parameters:

  • param – Effect parameter

  • val – Integer value

void gs_effect_set_matrix4(gs_eparam_t *param, const struct matrix4 *val)

Sets a matrix parameter.

Parameters:

  • param – Effect parameter

  • val – Matrix

void gs_effect_set_vec2(gs_eparam_t *param, const struct vec2 *val)

Sets a 2-component vector parameter.

Parameters:

  • param – Effect parameter

  • val – Vector

void gs_effect_set_vec3(gs_eparam_t *param, const struct vec3 *val)

Sets a 3-component vector parameter.

Parameters:

  • param – Effect parameter

  • val – Vector

void gs_effect_set_vec4(gs_eparam_t *param, const struct vec4 *val)

Sets a 4-component vector parameter.

Parameters:

  • param – Effect parameter

  • val – Vector

void gs_effect_set_color(gs_eparam_t *param, uint32_t argb)

Convenience function for setting a color value via an integer value.

Parameters:

  • param – Effect parameter

  • argb – Integer color value (i.e. hex value would be 0xAARRGGBB)

void gs_effect_set_texture(gs_eparam_t *param, gs_texture_t *val)

Sets a texture parameter.

Parameters:

  • param – Effect parameter

  • val – Texture

void gs_effect_set_texture_srgb(gs_eparam_t *param, gs_texture_t *val)

Sets a texture parameter using SRGB view if available.

Parameters:

  • param – Effect parameter

  • val – Texture

void gs_effect_set_val(gs_eparam_t *param, const void *val, size_t size)

Sets a parameter with data manually.

Parameters:

  • param – Effect parameter

  • val – Pointer to data

  • size – Size of data

void gs_effect_set_default(gs_eparam_t *param)

Sets the parameter to its default value

Param:

Effect parameter

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.

Parameters:

  • param – Effect parameter

  • sampler – Sampler state object

void *gs_effect_get_val(gs_eparam_t *param)

Returns a copy of the param’s current value.

Parameters:

  • param – Effect parameter

Returns:

A pointer to the copied byte value of the param’s current value. Freed with bfree().

void gs_effect_get_default_val(gs_eparam_t *param)

Returns a copy of the param’s default value.

Parameters:

  • param – Effect parameter

Returns:

A pointer to the copied byte value of the param’s default value. Freed with bfree().

size_t gs_effect_get_val_size(gs_eparam_t *param)

Returns the size in bytes of the param’s current value.

Parameters:

  • param – Effect parameter

Returns:

The size in bytes of the param’s current value.

size_t gs_effect_get_default_val_size(gs_eparam_t *param)

Returns the size in bytes of the param’s default value.

Parameters:

  • param – Effect parameter

Returns:

The size in bytes of the param’s default value.