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

Macros

#define BJ_LINE_STEPPED   BJ_LINE_MODE_STEPPED
#define BJ_LINE_WATERTIGHT   BJ_LINE_MODE_WATERTIGHT

Enumerations

enum  bj_line_mode { BJ_LINE_MODE_STEPPED = 0 , BJ_LINE_MODE_WATERTIGHT }
enum  bj_polyline_end { BJ_POLYLINE_END_OPEN = 0 , BJ_POLYLINE_END_CLOSED = 1 }

Functions

void bj_draw_line (struct bj_bitmap *bitmap, int x0, int y0, int x1, int y1, uint32_t pixel)
void bj_draw_line_mode (struct bj_bitmap *bitmap, int x0, int y0, int x1, int y1, bj_line_mode mode, uint32_t pixel)
void bj_draw_rectangle (struct bj_bitmap *bitmap, const struct bj_rect *area, uint32_t pixel)
void bj_draw_filled_rectangle (struct bj_bitmap *bitmap, const struct bj_rect *area, uint32_t pixel)
void bj_draw_triangle (struct bj_bitmap *bitmap, int x0, int y0, int x1, int y1, int x2, int y2, uint32_t color)
void bj_draw_filled_triangle (struct bj_bitmap *bitmap, int x0, int y0, int x1, int y1, int x2, int y2, uint32_t color)
void bj_draw_circle (struct bj_bitmap *bitmap, int cx, int cy, int radius, uint32_t color)
void bj_draw_filled_circle (struct bj_bitmap *bitmap, int cx, int cy, int radius, uint32_t color)
void bj_draw_polyline (struct bj_bitmap *bitmap, size_t count, const int *x, const int *y, bj_polyline_end end, uint32_t color)
void bj_draw_polyline_mode (struct bj_bitmap *bitmap, size_t count, const int *x, const int *y, bj_polyline_end end, bj_line_mode mode, uint32_t color)

Pixel enumeration

The drawing functions above answer "paint this shape".

The functions below answer a different question: "which pixels does this shape touch?" — and answer it without touching a bitmap at all.

The same walk drives both: bj_draw_line and bj_enumerate_line_pixels visit exactly the same pixels, in the same order. Only the destination differs.

This is what you want for edge walking in a software rasteriser, ray casting over a tile map, line-of-sight tests, or picking — anywhere the coordinates are the result and no pixel is ever written.

typedef bj_bool(* bj_pixel_fn) (void *user_data, int x, int y)
typedef bj_bool(* bj_cell_fn) (void *user_data, int x, int y, bj_real t)
void bj_enumerate_line_pixels (int x0, int y0, int x1, int y1, bj_pixel_fn callback, void *user_data)
void bj_line_pixels (int x0, int y0, int x1, int y1, bj_pixel_fn callback, void *user_data)
void bj_enumerate_circle_pixels (int cx, int cy, int radius, bj_pixel_fn callback, void *user_data)
void bj_circle_pixels (int cx, int cy, int radius, bj_pixel_fn callback, void *user_data)
void bj_enumerate_grid_ray_cells (bj_real x0, bj_real y0, bj_real x1, bj_real y1, bj_cell_fn callback, void *user_data)
void bj_grid_ray_cells (bj_real x0, bj_real y0, bj_real x1, bj_real y1, bj_cell_fn callback, void *user_data)

Detailed Description

Draw lines, shapes, and outlines into a bitmap.

These functions draw simple geometric shapes into a bj_bitmap. pixels, lines, rectangles, triangles, circles, and polylines (a series of connected line segments). Each function writes directly into the destination bitmap's pixels; there's no draw queue or scene graph. The pattern is:

  1. Get a bitmap to draw into (commonly the window's framebuffer via bj_render_target_bitmap).
  2. Pick a colour: build a uint32_t packed in the bitmap's pixel format with bj_pack_bitmap_rgb.
  3. Call as many drawing functions as you need; they modify the bitmap in place.
  4. Push the bitmap to the screen with bj_invalidate_window.
static void on_draw(struct bj_window* w, struct bj_render_target* t,
const struct bj_rect* dirty, void* user_data) {
uint32_t red = bj_pack_bitmap_rgb(fb, 0xFF, 0x00, 0x00);
bj_draw_filled_circle(fb, 320, 240, 100, red);
bj_draw_rectangle(fb, &(bj_rect){.x=10,.y=10,.w=64,.h=64}, red);
}
/* in setup: bj_set_window_draw_callback(window, on_draw, NULL);
bj_invalidate_window(window); *‍/
static void on_draw(struct bj_window *w, struct bj_render_target *target, const struct bj_rect *dirty, void *user_data)
Definition bitmap_blit.c:32
void bj_clear_bitmap(struct bj_bitmap *bitmap)
Fills the entire bitmap with the clear colour.
uint32_t bj_pack_bitmap_rgb(struct bj_bitmap *bitmap, uint8_t red, uint8_t green, uint8_t blue)
Pack an (R, G, B) triple into the bitmap's native pixel format.
struct bj_render_target bj_render_target
Definition api.h:369
struct bj_bitmap bj_bitmap
Definition api.h:340
struct bj_window bj_window
Definition api.h:384
void bj_draw_rectangle(struct bj_bitmap *bitmap, const struct bj_rect *area, uint32_t pixel)
Draws a rectangle in the given bitmap.
void bj_draw_filled_circle(struct bj_bitmap *bitmap, int cx, int cy, int radius, uint32_t color)
Draw a filled circle onto a bitmap.
Axis-aligned rectangle: a top-left corner plus a width and height.
Definition rect.h:33
struct bj_bitmap * bj_render_target_bitmap(struct bj_render_target *target)
Reach the software framebuffer behind a render target.

Outlined or filled

Rectangles, triangles, and circles each come in two flavours: bj_draw_rectangle / bj_draw_filled_rectangle and so on. "Outlined" draws just the edge; "filled" colours every pixel inside. Lines and polylines are obviously line-only.

Drawing is clipped to the bitmap

Shapes may cross the edges of the bitmap: the pixels that fall outside it are skipped. A line or an outline is still walked one pixel at a time, so drawing far outside the bitmap costs as much as drawing inside it.

See also
bj_clear_bitmap to wipe the destination first, drawing_2d.c for every primitive in one program, drawing_text.c for text rendering on top of these primitives.

Macro Definition Documentation

◆ BJ_LINE_STEPPED

#define BJ_LINE_STEPPED   BJ_LINE_MODE_STEPPED
Deprecated
Renamed to BJ_LINE_MODE_STEPPED. Removed in 2.0.

Definition at line 97 of file draw.h.

◆ BJ_LINE_WATERTIGHT

#define BJ_LINE_WATERTIGHT   BJ_LINE_MODE_WATERTIGHT
Deprecated
Renamed to BJ_LINE_MODE_WATERTIGHT. Removed in 2.0.

Definition at line 99 of file draw.h.

Typedef Documentation

◆ bj_cell_fn

typedef bj_bool(* bj_cell_fn) (void *user_data, int x, int y, bj_real t)

Callback invoked once per grid cell entered by a ray.

Parameters
user_dataOpaque pointer forwarded from the enumerating call.
xCell column.
yCell row.
tWhere the ray enters this cell, as a fraction of its total length: 0 at the origin, 1 at the far end.
Returns
BJ_TRUE to keep walking, BJ_FALSE to stop at once.

t is the reason this callback differs from bj_pixel_fn — it is the hit distance a ray caster needs, and it cannot be recovered afterwards from the cell coordinates alone.

Definition at line 408 of file draw.h.

◆ bj_pixel_fn

typedef bj_bool(* bj_pixel_fn) (void *user_data, int x, int y)

Callback invoked once per visited pixel.

Parameters
user_dataOpaque pointer forwarded from the enumerating call.
xPixel column.
yPixel row.
Returns
BJ_TRUE to keep walking, BJ_FALSE to stop at once.

Returning BJ_FALSE is how you stop early — a line-of-sight test stops at the first wall rather than walking to the end of the ray.

Warning
Coordinates are not clipped to any bitmap: the walk reports what the geometry touches, including negative coordinates. Clamp in the callback if you intend to write pixels.

Definition at line 388 of file draw.h.

Enumeration Type Documentation

◆ bj_line_mode

How a line decides which pixels it touches.

Both modes join the same two endpoints; they disagree only about the corners of the staircase a sloped line makes.

Choosing

BJ_LINE_MODE_STEPPED is what you want to see: it is thinner and it is what every drawing program has always produced.

BJ_LINE_MODE_WATERTIGHT is what you want to rely on: an outline drawn with it has no diagonal gaps, so a fill cannot escape through a corner and a ray cannot slip between two walls that share one.

Enumerator
BJ_LINE_MODE_STEPPED 

Diagonal steps allowed, one pixel per step along the major axis.

The thinnest line joining two points, and the historical default.

BJ_LINE_MODE_WATERTIGHT 

No diagonal steps: consecutive pixels differ along one axis only, so the line has no gap at any corner.

Slightly fatter on slopes.

Definition at line 82 of file draw.h.

◆ bj_polyline_end

Whether a polyline's last vertex connects back to its first.

Values match BJ_FALSE / BJ_TRUE so pre-2.0 code that passed a bj_bool keeps working.

Enumerator
BJ_POLYLINE_END_OPEN 

The polyline is left open.

BJ_POLYLINE_END_CLOSED 

An extra segment closes the polyline into a loop.

Definition at line 107 of file draw.h.

Function Documentation

◆ bj_circle_pixels()

void bj_circle_pixels ( int cx,
int cy,
int radius,
bj_pixel_fn callback,
void * user_data )
Deprecated
Renamed to bj_enumerate_circle_pixels. Removed in 2.0.

◆ bj_draw_circle()

void bj_draw_circle ( struct bj_bitmap * bitmap,
int cx,
int cy,
int radius,
uint32_t color )

Draw the outline of a circle onto a bitmap.

Uses the midpoint circle algorithm (integer arithmetic).

Parameters
bitmapTarget bitmap, or NULL, which draws nothing.
cxX-coordinate of circle centre (pixels).
cyY-coordinate of circle centre (pixels).
radiusCircle radius in pixels; 0 or less draws the centre pixel.
colorPixel value packed in the bitmap's format (see bj_pack_bitmap_rgb).

◆ bj_draw_filled_circle()

void bj_draw_filled_circle ( struct bj_bitmap * bitmap,
int cx,
int cy,
int radius,
uint32_t color )

Draw a filled circle onto a bitmap.

Fills the pixels of the outline bj_draw_circle draws, and every pixel between them on each row.

Parameters
bitmapTarget bitmap, or NULL, which draws nothing.
cxX-coordinate of circle centre (pixels).
cyY-coordinate of circle centre (pixels).
radiusCircle radius in pixels; 0 or less draws the centre pixel.
colorPixel value packed in the bitmap's format (see bj_pack_bitmap_rgb).
Examples
drawing_2d.c, interpolation.c, physics_kinematics.c, physics_particle.c, pong.c, and start.c.

Referenced by draw(), draw(), draw(), draw(), on_draw(), and on_draw().

◆ bj_draw_filled_rectangle()

void bj_draw_filled_rectangle ( struct bj_bitmap * bitmap,
const struct bj_rect * area,
uint32_t pixel )

Draws a filled rectangle in the given bitmap.

The function fills the w × h pixels of area, from (x, y) to (x + w - 1, y + h - 1).

Parameters
bitmapThe bitmap object, or NULL, which draws nothing.
areaThe rectangle to draw, or NULL, which draws nothing.
pixelThe line pixel value.
Examples
bitmap_blit_colorkey.c, drawing_2d.c, maze.c, pixel_enumeration.c, pong.c, and random_distribution.c.

Referenced by draw(), draw(), draw_maze(), fill_cell(), and setup().

◆ bj_draw_filled_triangle()

void bj_draw_filled_triangle ( struct bj_bitmap * bitmap,
int x0,
int y0,
int x1,
int y1,
int x2,
int y2,
uint32_t color )

Draws a filled triangle given its 3 corners.

Each row is filled from the leftmost to the rightmost pixel that bj_draw_triangle draws on it with the same corners, in the same order, so the fill covers that outline.

Parameters
bitmapThe bitmap object, or NULL, which draws nothing.
x0The X coordinate of the first triangle vertex.
y0The Y coordinate of the first triangle vertex.
x1The X coordinate of the second triangle vertex.
y1The Y coordinate of the second triangle vertex.
x2The X coordinate of the third triangle vertex.
y2The Y coordinate of the third triangle vertex.
colorThe fill colour.
Examples
drawing_2d.c.

Referenced by draw().

◆ bj_draw_line()

void bj_draw_line ( struct bj_bitmap * bitmap,
int x0,
int y0,
int x1,
int y1,
uint32_t pixel )

Draws a line of pixels in the given bitmap.

The line is drawn for each pixel between p0 and p1.

Parameters
bitmapThe bitmap object, or NULL, which draws nothing.
x0The X coordinate of the first point in the line.
y0The Y coordinate of the first point in the line.
x1The X coordinate of the second point in the line.
y1The Y coordinate of the second point in the line.
pixelThe line pixel value.

Draws a BJ_LINE_MODE_STEPPED line. Use bj_draw_line_mode to choose.

All pairs of int coordinates are defined: the walk runs in 64-bit state. The stepped walk visits every pixel between the points, however far they sit from the bitmap; a line that reaches the drawing area from far away costs what bj_draw_line_mode with BJ_LINE_MODE_WATERTIGHT does not, which clips to the bitmap first.

See also
bj_enumerate_line_pixels to walk this line without Drawing it.
Examples
maze.c, pixel_enumeration.c, and random_distribution.c.

Referenced by draw(), draw(), draw_grid_lines(), and draw_maze().

◆ bj_draw_line_mode()

void bj_draw_line_mode ( struct bj_bitmap * bitmap,
int x0,
int y0,
int x1,
int y1,
bj_line_mode mode,
uint32_t pixel )

Draws a line of pixels, choosing which ones it claims.

Parameters
bitmapThe bitmap object, or NULL, which draws nothing.
x0The X coordinate of the first point in the line.
y0The Y coordinate of the first point in the line.
x1The X coordinate of the second point in the line.
y1The Y coordinate of the second point in the line.
modeWhich pixels the line claims (see bj_line_mode).
pixelThe line pixel value.

bj_draw_line is the shorthand for BJ_LINE_MODE_STEPPED. This is the general form, and the only one that can take the mode from a variable.

See also
bj_enumerate_line_pixels to walk a stepped line without Drawing it, bj_enumerate_grid_ray_cells for the watertight walk, which also reports how far along the ray each Pixel Definition lies.
Examples
drawing_2d.c.

Referenced by draw().

◆ bj_draw_polyline()

void bj_draw_polyline ( struct bj_bitmap * bitmap,
size_t count,
const int * x,
const int * y,
bj_polyline_end end,
uint32_t color )

Draw a polyline from C-style coordinate arrays.

Draws line segments between successive vertex pairs (x[i], y[i]) -> (x[i+1], y[i+1]). With BJ_POLYLINE_END_CLOSED and count >= 2, an extra segment connects the last vertex to the first.

Parameters
bitmapTarget bitmap, or NULL, which draws nothing.
xPointer to array of x coordinates (length >= count), or NULL, which draws nothing.
yPointer to array of y coordinates (length >= count), or NULL, which draws nothing.
countNumber of vertices. Segments drawn for i = 0..count-2.
endBJ_POLYLINE_END_OPEN or BJ_POLYLINE_END_CLOSED.
colorPixel value packed in the bitmap's format (see bj_pack_bitmap_rgb).

Draws BJ_LINE_MODE_STEPPED segments. Use bj_draw_polyline_mode to choose.

Examples
drawing_2d.c.

Referenced by draw().

◆ bj_draw_polyline_mode()

void bj_draw_polyline_mode ( struct bj_bitmap * bitmap,
size_t count,
const int * x,
const int * y,
bj_polyline_end end,
bj_line_mode mode,
uint32_t color )

Draw a polyline, choosing which pixels its segments claim.

Parameters
bitmapTarget bitmap, or NULL, which draws nothing.
xPointer to array of x coordinates (length >= count), or NULL, which draws nothing.
yPointer to array of y coordinates (length >= count), or NULL, which draws nothing.
countNumber of vertices. Segments drawn for i = 0..count-2.
endBJ_POLYLINE_END_OPEN or BJ_POLYLINE_END_CLOSED.
modeWhich pixels each segment claims (see bj_line_mode).
colorPixel value packed in the bitmap's format (see bj_pack_bitmap_rgb).
Closed outlines

A closed polyline drawn with BJ_LINE_MODE_WATERTIGHT encloses its interior with no diagonal gaps, which is what a fill needs in order to stay inside it. With BJ_LINE_MODE_STEPPED the outline looks right but leaks at every corner of every slope.

◆ bj_draw_rectangle()

void bj_draw_rectangle ( struct bj_bitmap * bitmap,
const struct bj_rect * area,
uint32_t pixel )

Draws a rectangle in the given bitmap.

The function draws the outline of area: the first and last of its rows and columns, within the same w × h pixels that bj_draw_filled_rectangle fills. An area of width or height 0 draws nothing.

Parameters
bitmapThe bitmap object, or NULL, which draws nothing.
areaThe rectangle to draw, or NULL, which draws nothing.
pixelThe line pixel value.
Examples
drawing_2d.c, random_distribution.c, and start.c.

Referenced by draw(), and on_draw().

◆ bj_draw_triangle()

void bj_draw_triangle ( struct bj_bitmap * bitmap,
int x0,
int y0,
int x1,
int y1,
int x2,
int y2,
uint32_t color )

Draws the edges of a triangle given its 3 corners.

Parameters
bitmapThe bitmap object, or NULL, which draws nothing.
x0The X coordinate of the first triangle vertex.
y0The Y coordinate of the first triangle vertex.
x1The X coordinate of the second triangle vertex.
y1The Y coordinate of the second triangle vertex.
x2The X coordinate of the third triangle vertex.
y2The Y coordinate of the third triangle vertex.
colorThe line colour.
Examples
drawing_2d.c.

Referenced by draw().

◆ bj_enumerate_circle_pixels()

void bj_enumerate_circle_pixels ( int cx,
int cy,
int radius,
bj_pixel_fn callback,
void * user_data )

Reports every pixel a circle outline touches, without drawing anything.

Parameters
cxCentre, X coordinate.
cyCentre, Y coordinate.
radiusRadius in pixels. A radius of 0 or less reports the centre pixel alone.
callbackInvoked once per pixel. Does nothing when 0.
user_dataPassed through to callback untouched, NULL included.

Walks the same midpoint circle as bj_draw_circle, reporting the eight symmetric points of each step together, in the order the mirrors give: (cx + x, cy + y) first, then (cx + y, cy + x), (cx - y, cy + x), (cx - x, cy + y), and around.

Note
Pixels on the octant seams are reported more than once — the eight symmetric points coincide there. That is harmless when drawing, since writing a pixel twice changes nothing, but a callback that counts or accumulates must account for it.
See also
bj_draw_circle for the Drawing counterpart.

◆ bj_enumerate_grid_ray_cells()

void bj_enumerate_grid_ray_cells ( bj_real x0,
bj_real y0,
bj_real x1,
bj_real y1,
bj_cell_fn callback,
void * user_data )

Reports every grid cell a ray passes through.

Parameters
x0Ray origin, X coordinate, in cell units.
y0Ray origin, Y coordinate, in cell units.
x1Ray end, X coordinate, in cell units.
y1Ray end, Y coordinate, in cell units.
callbackInvoked once per cell entered. Does nothing when 0.
user_dataPassed through to callback untouched, NULL included.

Coordinates are continuous and expressed in cells: (2.5, 3.5) is the centre of cell (2, 3). Cell indices are the floor of the coordinates and may be negative. When the ray crosses a cell corner exactly, the walk steps along Y first.

Why this is not a line walk

This walk is supercovering: it reports every cell the ray crosses, so two consecutive cells always differ along one axis only — never both. A ray can therefore never slip diagonally between two walls that share a corner. That is what a line-of-sight or ray-casting test needs, and what the Bresenham walk of bj_enumerate_line_pixels cannot give.

The cell containing the origin is always reported first, with t of 0.

Examples
pixel_enumeration.c.

Referenced by draw().

◆ bj_enumerate_line_pixels()

void bj_enumerate_line_pixels ( int x0,
int y0,
int x1,
int y1,
bj_pixel_fn callback,
void * user_data )

Reports every pixel a line touches, without drawing anything.

Parameters
x0First point, X coordinate.
y0First point, Y coordinate.
x1Second point, X coordinate.
y1Second point, Y coordinate.
callbackInvoked once per pixel. Does nothing when 0.
user_dataPassed through to callback untouched, NULL included.

Walks the same Bresenham line as bj_draw_line, visiting the same pixels in the same order, from (x0, y0) to (x1, y1) inclusive. A line whose endpoints are equal reports exactly one pixel.

Warning
This is not a grid traversal. Bresenham picks one pixel per step along the major axis, so a diagonal move jumps corner to corner and skips the two cells sharing that corner. For line of sight or ray casting over tiles, that lets a ray slip through the corner of a wall — use bj_enumerate_grid_ray_cells instead.
See also
bj_draw_line for the Drawing counterpart.
Examples
pixel_enumeration.c.

Referenced by draw().

◆ bj_grid_ray_cells()

void bj_grid_ray_cells ( bj_real x0,
bj_real y0,
bj_real x1,
bj_real y1,
bj_cell_fn callback,
void * user_data )
Deprecated
Renamed to bj_enumerate_grid_ray_cells. Removed in 2.0.

◆ bj_line_pixels()

void bj_line_pixels ( int x0,
int y0,
int x1,
int y1,
bj_pixel_fn callback,
void * user_data )
Deprecated
Renamed to bj_enumerate_line_pixels. Removed in 2.0.