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.