Shaders

Software shader-like API for bj_bitmap. More...

Collaboration diagram for Shaders:

Detailed Description

This API provides facilities to manipulate the pixels of a bj_bitmap object in a similar way GPU shaders do.

A shader function is any user-provided function that corresponds to the bj_bitmap_shading_fn_t signature. Such function is passed to bj_bitmap_apply_shader which calls the shader fonction on every pixel of the bitmap.

This header file also provides some math functions usually found in most shader languages, such as bj_step and bj_smoothstep. Other useful math-related functions can be found in math.h.

Macros
#define	BJ_SHADER_STANDARD_FLAGS   (BJ_SHADER_INVERT_Y | BJ_SHADER_CLAMP_COLOR | BJ_SHADER_NORMALIZE_COORDS | BJ_SHADER_CENTER_COORDS)
	Flagset alias for bj_bitmap_apply_shader.

Typedefs
typedef int(*	bj_bitmap_shading_fn_t) (bj_vec3 out_color, const bj_vec2 pixel_coord, void *user_data)
	Function type for a bitmap shading operation.
typedef enum bj_shader_flag_t	bj_shader_flag
	Shader input control flags.

Enumerations
enum	bj_shader_flag_t {   BJ_SHADER_INVERT_X = 0x01 , BJ_SHADER_INVERT_Y = 0x02 , BJ_SHADER_CLAMP_COLOR = 0x04 , BJ_SHADER_NORMALIZE_COORDS = 0x08 ,   BJ_SHADER_CENTER_COORDS = 0x10 }
	Shader input control flags. More...

Functions
float	bj_clamp (float x, float min, float max)
	Clamps a float between a minimum and a maximum value.
float	bj_step (float edge, float x)
	Returns 0.0 if x < edge, else 1.0.
float	bj_smoothstep (float edge0, float edge1, float x)
	Performs smooth Hermite interpolation between 0 and 1 over a range.
float	bj_fract (float x)
	Returns the fractional part of a float.
int	bj_mod (float x, float y)
	Computes a floor-style modulus between two floats.
void	bj_bitmap_apply_shader (bj_bitmap *p_bitmap, bj_bitmap_shading_fn_t p_shader, void *p_data, uint8_t flags)
	Applies a shader function to every pixel in a bitmap.

Macro Definition Documentation

BJ_SHADER_STANDARD_FLAGS

#define BJ_SHADER_STANDARD_FLAGS   (BJ_SHADER_INVERT_Y | BJ_SHADER_CLAMP_COLOR | BJ_SHADER_NORMALIZE_COORDS | BJ_SHADER_CENTER_COORDS)

This flagset value can be passed to bj_bitmap_apply_shader and corresponds to the most commonly used flags:

• Invert Y (orient from bottom-left corner),
• Clamp color between 0.0 and 1.0,
• Convert pixel coordinates in the [-1.0 ; 1.0] space

Typedef Documentation

bj_bitmap_shading_fn_t

typedef int(* bj_bitmap_shading_fn_t) (bj_vec3 out_color, const bj_vec2 pixel_coord, void *user_data)

A shader function pointer is provided to bj_bitmap_apply_shader and will be called for each pixel of the provided bitmap.

Parameters

out_color	Pointer to the output color (in linear RGB space).
pixel_coord	Position of the pixel in 2D coordinates.
user_data	Optional user data passed through from bj_bitmap_apply_shader.

Returns

1 on success, non-zero if the pixel should be skipped or discarded.

bj_shader_flag

typedef enum bj_shader_flag_t bj_shader_flag

These flags are passed to bj_bitmap_apply_shader to control how the inputs to the shader function (bj_bitmap_shading_fn_t) are transformed. They affect how the pixel coordinates are interpreted and how the shader's output color is handled.

Enumeration Type Documentation

bj_shader_flag_t

enum bj_shader_flag_t

These flags are passed to bj_bitmap_apply_shader to control how the inputs to the shader function (bj_bitmap_shading_fn_t) are transformed. They affect how the pixel coordinates are interpreted and how the shader's output color is handled.

Enumerator
BJ_SHADER_INVERT_X	Invert the X coordinate of the input pixel. By default, the coordinate system matches that of bj_bitmap. The origin is at the top-left corner, with X increasing to the right and Y increasing downward, ranging from 0 to the bitmap's width and height. When this flag is set, the X coordinate is mirrored as if the bitmap were flipped horizontally. This flag can be combined with BJ_SHADER_NORMALIZE_COORDS and BJ_SHADER_CENTER_COORDS. It is applied after those transformations.
BJ_SHADER_INVERT_Y	Invert the Y coordinate of the input pixel. By default, the coordinate system matches that of bj_bitmap. The origin is at the top-left corner, with X increasing to the right and Y increasing downward, ranging from 0 to the bitmap's width and height. When this flag is set, the Y coordinate is mirrored as if the bitmap were flipped vertically. This flag can be combined with BJ_SHADER_NORMALIZE_COORDS and BJ_SHADER_CENTER_COORDS. It is applied after those transformations.
BJ_SHADER_CLAMP_COLOR	Clamp the output color to the range [0.0, 1.0]. The shader function is expected to output RGB components in the range [0.0, 1.0]. If this flag is set, the output color will automatically be clamped to that range, preventing overflow or underflow. This can help avoid artifacts if the shader generates values outside the valid range.
BJ_SHADER_NORMALIZE_COORDS	Normalize pixel coordinates to the [0.0, 1.0] range. Converts the pixel's X and Y coordinates into normalized values between 0.0 and 1.0, based on the width and height of the bitmap. This transformation maintains the original orientation (top-left origin), unless combined with BJ_SHADER_INVERT_X or BJ_SHADER_INVERT_Y. If used together with BJ_SHADER_CENTER_COORDS, the final coordinate space becomes [-1.0, 1.0], centered around the origin.
BJ_SHADER_CENTER_COORDS	Center pixel coordinates around the origin. Translates the coordinate system so that (0,0) represents the center of the bitmap. By default, pixel coordinates range from (0,0) to (width, height). When this flag is enabled: If used without BJ_SHADER_NORMALIZE_COORDS, coordinates are shifted into the range: X: [-width/2, width/2] Y: [-height/2, height/2] If used with BJ_SHADER_NORMALIZE_COORDS, coordinates are shifted into the range: X, Y ∈ [-1.0, 1.0] This transformation is applied before coordinate inversion flags.

Function Documentation

bj_bitmap_apply_shader()

void bj_bitmap_apply_shader	(	bj_bitmap *	p_bitmap,
		bj_bitmap_shading_fn_t	p_shader,
		void *	p_data,
		uint8_t	flags )

The shader function is called per pixel, with access to the 2D coordinate and a reference to output a linear RGB color. Optional user data and behavior flags can be provided.

Parameters

p_bitmap	Pointer to the target bitmap to be modified.
p_shader	A pointer to the shader function to call per pixel.
p_data	User-defined data passed to each shader call.
flags	Combination of bj_shader_flag controlling coordinate and color behavior.

Examples

shaders.c.

bj_clamp()

float bj_clamp	(	float	x,
		float	min,
		float	max )

Parameters

x	The input value.
min	The minimum value allowed.
max	The maximum value allowed.

Returns

The clamped value.

bj_fract()

float bj_fract

(

float

x

)

Parameters

x	The input value.

Returns

The fractional part (x - floor(x)).

bj_mod()

int bj_mod	(	float	x,
		float	y )

Parameters

x	The dividend.
y	The divisor.

Returns

The result of x mod y, using floor-based logic.

bj_smoothstep()

float bj_smoothstep	(	float	edge0,
		float	edge1,
		float	x )

Parameters

edge0	The lower bound of the transition.
edge1	The upper bound of the transition.
x	The input value.

Returns

The smoothed value in [0, 1].

bj_step()

float bj_step	(	float	edge,
		float	x )

Often used for binary thresholding in shaders.

Parameters

edge	The threshold edge.
x	The input value.

Returns

0.0 or 1.0 depending on x's relationship to edge.