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.