|
Banjo API 1.1.0-alpha
Low-level C99 game development API
|
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_FLAG_INVERT_X = 0x01 , BJ_SHADER_FLAG_INVERT_Y = 0x02 , BJ_SHADER_FLAG_CLAMP_COLOR = 0x04 , BJ_SHADER_FLAG_NORMALIZE_COORDS = 0x08 , BJ_SHADER_FLAG_CENTER_COORDS = 0x10 } |
Functions | |
| void | bj_shade_bitmap (struct bj_bitmap *bitmap, bj_bitmap_shading_fn shader, void *data, uint8_t flags) |
| void | bj_shader_bitmap (struct bj_bitmap *bitmap, bj_bitmap_shading_fn shader, void *data, uint8_t flags) |
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_shade_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_shade_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.
shaders.c for a runnable demo (a port of a Shadertoy piece, to show what's reachable in pure CPU). | #define BJ_SHADER_CENTER_COORDS BJ_SHADER_FLAG_CENTER_COORDS |
| #define BJ_SHADER_CLAMP_COLOR BJ_SHADER_FLAG_CLAMP_COLOR |
| #define BJ_SHADER_FLAGS_STANDARD (BJ_SHADER_FLAG_INVERT_Y | BJ_SHADER_FLAG_CLAMP_COLOR | BJ_SHADER_FLAG_NORMALIZE_COORDS | BJ_SHADER_FLAG_CENTER_COORDS) |
Flagset alias for bj_shade_bitmap.
This flagset value can be passed to bj_shade_bitmap and corresponds to the most commonly used flags:
Definition at line 186 of file shader.h.
Referenced by on_draw().
| #define BJ_SHADER_INVERT_X BJ_SHADER_FLAG_INVERT_X |
| #define BJ_SHADER_INVERT_Y BJ_SHADER_FLAG_INVERT_Y |
| #define BJ_SHADER_NORMALIZE_COORDS BJ_SHADER_FLAG_NORMALIZE_COORDS |
| #define BJ_SHADER_STANDARD_FLAGS BJ_SHADER_FLAGS_STANDARD |
| 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_shade_bitmap and will be called for each pixel of the provided bitmap.
| out_color | Pointer to the output colour, each component from 0 to
|
| pixel_coord | Position of the pixel's top-left corner, transformed by the flags of bj_shade_bitmap. |
| user_data | Optional user data passed through from bj_shade_bitmap. |
out_color to the pixel; return 0 (or negative) to leave the pixel unchanged (skip it). For example, an opaque shader returns 1 for every pixel. | typedef enum bj_shader_flag bj_shader_flag |
| enum bj_shader_flag |
Shader input control flags.
These flags are passed to bj_shade_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_FLAG_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: a pixel's coordinate is its top-left corner, from 0 to the bitmap's width and height minus 1. When this flag is set, the X coordinate is mirrored as if the bitmap were flipped horizontally: x becomes width - x, 1 - x once normalised, and -x once centred. This flag can be combined with BJ_SHADER_FLAG_NORMALIZE_COORDS and BJ_SHADER_FLAG_CENTER_COORDS. It is applied after those transformations. |
| BJ_SHADER_FLAG_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: a pixel's coordinate is its top-left corner, from 0 to the bitmap's width and height minus 1. When this flag is set, the Y coordinate is mirrored as if the bitmap were flipped vertically: y becomes height - y, 1 - y once normalised, and -y once centred. This flag can be combined with BJ_SHADER_FLAG_NORMALIZE_COORDS and BJ_SHADER_FLAG_CENTER_COORDS. It is applied after those transformations. |
| BJ_SHADER_FLAG_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 before it is written. The conversion to bytes saturates in any case, a component below 0, or NaN, giving 0 and one above 1 giving 255, so the flag changes no pixel; it is kept for compatibility. |
| BJ_SHADER_FLAG_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, by dividing them by the width and height of the bitmap: the last pixel of a row of 4 is at 0.75. This transformation maintains the original orientation (top-left origin), unless combined with BJ_SHADER_FLAG_INVERT_X or BJ_SHADER_FLAG_INVERT_Y. If used together with BJ_SHADER_FLAG_CENTER_COORDS, the final coordinate space becomes [-1.0, 1.0), centred around the origin. The ranges are half-open because a coordinate names a pixel's top-left corner; an inverted axis spans (0.0, 1.0] instead. |
| BJ_SHADER_FLAG_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 over [0, width) and [0, height), a coordinate naming a pixel's top-left corner. When this flag is enabled:
An inverted axis spans the mirrored range, closed at its upper end. This transformation is applied before coordinate inversion flags. |
| void bj_shade_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 the pixel's colour, each component the stored byte divided by 255, with no gamma conversion, which it may replace. Optional user data and behaviour flags can be provided.
| bitmap | Pointer to the target bitmap to be modified, or 0, which does nothing. |
| shader | A pointer to the shader function to call per pixel, or 0, which does nothing. |
| data | User-defined data passed to each shader call, 0 included. |
| flags | Combination of bj_shader_flag controlling coordinate and colour behaviour. |
Referenced by on_draw().
| void bj_shader_bitmap | ( | struct bj_bitmap * | bitmap, |
| bj_bitmap_shading_fn | shader, | ||
| void * | data, | ||
| uint8_t | flags ) |