Macros | |
| #define | BJ_SHADER_STANDARD_FLAGS (BJ_SHADER_INVERT_Y | BJ_SHADER_CLAMP_COLOR | BJ_SHADER_NORMALIZE_COORDS | BJ_SHADER_CENTER_COORDS) |
Typedefs | |
| typedef int(* | bj_bitmap_shading_fn) (struct bj_vec3 *out_color, const struct bj_vec2 pixel_coord, void *user_data) |
| typedef enum bj_shader_flag | bj_shader_flag |
Enumerations | |
| enum | bj_shader_flag { 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 } |
Functions | |
| void | bj_shader_bitmap (struct bj_bitmap *bitmap, bj_bitmap_shading_fn shader, void *data, uint8_t flags) |
Detailed Description
Fill every pixel of a bitmap with the result of a small function you supply.
A shader, in this subsystem, is a function of yours that takes the coordinates of one pixel (and a bit of context) and returns the colour that pixel should be. You write the function, hand it to bj_shader_bitmap, and Banjo runs it for every pixel of the target bitmap. The name comes from the much fancier shaders of GPU programming, same idea, but here it's pure C running on the CPU.
This is the right tool for procedurally generated images: patterns, gradients, fractals, animated visual effects, noise fields. Anything where every pixel's colour can be computed from its position (and maybe a clock, a seed, some parameters you thread through) is a one-liner with this API.
Your function must match the bj_bitmap_shading_fn signature. bj_shader_bitmap walks the bitmap top-to-bottom, left-to-right and writes whatever you return into each pixel.
For the math you'll commonly want inside a shader (sin/cos, fract, smoothstep, vector ops, normalisation) look at Math and the vec.h / mat.h headers.
- See also
shaders.cfor a runnable demo (a port of a Shadertoy piece, to show what's reachable in pure CPU).
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) |
Flagset alias for bj_shader_bitmap.
This flagset value can be passed to bj_shader_bitmap and corresponds to the most commonly used flags:
- Invert Y (orient from bottom-left corner),
- Clamp colour between 0.0 and 1.0,
- Convert pixel coordinates in the [-1.0 ; 1.0] space
- Examples
- shaders.c.
Definition at line 162 of file shader.h.
Referenced by on_draw().
Typedef Documentation
◆ bj_bitmap_shading_fn
| typedef int(* bj_bitmap_shading_fn) (struct bj_vec3 *out_color, const struct bj_vec2 pixel_coord, void *user_data) |
Function type for a bitmap shading operation.
A shader function pointer is provided to bj_shader_bitmap and will be called for each pixel of the provided bitmap.
- Parameters
-
out_color Pointer to the output colour (in linear RGB space). pixel_coord Position of the pixel in 2D coordinates. user_data Optional user data passed through from bj_shader_bitmap.
- Returns
- Return a value > 0 to WRITE the computed
out_colorto the pixel; return 0 (or negative) to leave the pixel unchanged (skip it). For example, an opaque shader returns 1 for every pixel.
◆ bj_shader_flag
| typedef enum bj_shader_flag bj_shader_flag |
Enumeration Type Documentation
◆ bj_shader_flag
| enum bj_shader_flag |
Shader input control flags.
These flags are passed to bj_shader_bitmap to control how the inputs to the shader function (bj_bitmap_shading_fn) are transformed. They affect how the pixel coordinates are interpreted and how the shader's output colour 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 colour 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 colour 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 | Normalise pixel coordinates to the [0.0, 1.0] range. Converts the pixel's X and Y coordinates into normalised 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], centred around the origin. |
| BJ_SHADER_CENTER_COORDS | Centre pixel coordinates around the origin. Translates the coordinate system so that (0,0) represents the centre of the bitmap. By default, pixel coordinates range from (0,0) to (width, height). When this flag is enabled:
This transformation is applied before coordinate inversion flags. |
Function Documentation
◆ bj_shader_bitmap()
| void bj_shader_bitmap | ( | struct bj_bitmap * | bitmap, |
| bj_bitmap_shading_fn | shader, | ||
| void * | data, | ||
| uint8_t | flags ) |
Applies a shader function to every pixel in a bitmap.
The shader function is called per pixel, with access to the 2D coordinate and a reference to output a linear RGB colour. Optional user data and behaviour flags can be provided.
- Parameters
-
bitmap Pointer to the target bitmap to be modified. shader A pointer to the shader function to call per pixel. data User-defined data passed to each shader call. flags Combination of bj_shader_flag controlling coordinate and colour behaviour.
- Examples
- shaders.c.
Referenced by on_draw().
