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 *pardam, 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.

Previous topic

Next topic

Effects (Shaders)¶