Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
Shaders
Collaboration diagram for Shaders:

Macros

#define BJ_SHADER_INVERT_X   BJ_SHADER_FLAG_INVERT_X
#define BJ_SHADER_INVERT_Y   BJ_SHADER_FLAG_INVERT_Y
#define BJ_SHADER_CLAMP_COLOR   BJ_SHADER_FLAG_CLAMP_COLOR
#define BJ_SHADER_NORMALIZE_COORDS   BJ_SHADER_FLAG_NORMALIZE_COORDS
#define BJ_SHADER_CENTER_COORDS   BJ_SHADER_FLAG_CENTER_COORDS
#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)
#define BJ_SHADER_STANDARD_FLAGS   BJ_SHADER_FLAGS_STANDARD

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)

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_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.

See also
shaders.c for a runnable demo (a port of a Shadertoy piece, to show what's reachable in pure CPU).

Macro Definition Documentation

◆ BJ_SHADER_CENTER_COORDS

#define BJ_SHADER_CENTER_COORDS   BJ_SHADER_FLAG_CENTER_COORDS
Deprecated
Renamed to BJ_SHADER_FLAG_CENTER_COORDS. Removed in 2.0.

Definition at line 174 of file shader.h.

◆ BJ_SHADER_CLAMP_COLOR

#define BJ_SHADER_CLAMP_COLOR   BJ_SHADER_FLAG_CLAMP_COLOR
Deprecated
Renamed to BJ_SHADER_FLAG_CLAMP_COLOR. Removed in 2.0.

Definition at line 170 of file shader.h.

◆ BJ_SHADER_FLAGS_STANDARD

Flagset alias for bj_shade_bitmap.

This flagset value can be passed to bj_shade_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 186 of file shader.h.

Referenced by on_draw().

◆ BJ_SHADER_INVERT_X

#define BJ_SHADER_INVERT_X   BJ_SHADER_FLAG_INVERT_X
Deprecated
Renamed to BJ_SHADER_FLAG_INVERT_X. Removed in 2.0.

Definition at line 166 of file shader.h.

◆ BJ_SHADER_INVERT_Y

#define BJ_SHADER_INVERT_Y   BJ_SHADER_FLAG_INVERT_Y
Deprecated
Renamed to BJ_SHADER_FLAG_INVERT_Y. Removed in 2.0.

Definition at line 168 of file shader.h.

◆ BJ_SHADER_NORMALIZE_COORDS

#define BJ_SHADER_NORMALIZE_COORDS   BJ_SHADER_FLAG_NORMALIZE_COORDS
Deprecated
Renamed to BJ_SHADER_FLAG_NORMALIZE_COORDS. Removed in 2.0.

Definition at line 172 of file shader.h.

◆ BJ_SHADER_STANDARD_FLAGS

#define BJ_SHADER_STANDARD_FLAGS   BJ_SHADER_FLAGS_STANDARD
Deprecated
Renamed to BJ_SHADER_FLAGS_STANDARD. Removed in 2.0.

Definition at line 189 of file shader.h.

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_shade_bitmap and will be called for each pixel of the provided bitmap.

Parameters
out_colorPointer to the output colour, each component from 0 to
  1. On entry it holds the pixel's current colour.
pixel_coordPosition of the pixel's top-left corner, transformed by the flags of bj_shade_bitmap.
user_dataOptional user data passed through from bj_shade_bitmap.
Returns
Return a value > 0 to WRITE the computed 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.

Definition at line 61 of file shader.h.

◆ bj_shader_flag

Definition at line 162 of file shader.h.

Enumeration Type Documentation

◆ 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.

Definition at line 71 of file shader.h.

Function Documentation

◆ bj_shade_bitmap()

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.

Parameters
bitmapPointer to the target bitmap to be modified, or 0, which does nothing.
shaderA pointer to the shader function to call per pixel, or 0, which does nothing.
dataUser-defined data passed to each shader call, 0 included.
flagsCombination of bj_shader_flag controlling coordinate and colour behaviour.
Examples
shaders.c.

Referenced by on_draw().

◆ bj_shader_bitmap()

void bj_shader_bitmap ( struct bj_bitmap * bitmap,
bj_bitmap_shading_fn shader,
void * data,
uint8_t flags )
Deprecated
Renamed to bj_shade_bitmap. Removed in 2.0.