|
Banjo API 1.1.0-alpha
Low-level C99 game development API
|
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) |
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:
bj_render_target_bitmap).bj_invalidate_window.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.
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.
drawing_2d.c for every primitive in one program, drawing_text.c for text rendering on top of these primitives. | #define BJ_LINE_STEPPED BJ_LINE_MODE_STEPPED |
| #define BJ_LINE_WATERTIGHT BJ_LINE_MODE_WATERTIGHT |
Callback invoked once per grid cell entered by a ray.
| user_data | Opaque pointer forwarded from the enumerating call. |
| x | Cell column. |
| y | Cell row. |
| t | Where the ray enters this cell, as a fraction of its total length: 0 at the origin, 1 at the far end. |
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.
| typedef bj_bool(* bj_pixel_fn) (void *user_data, int x, int y) |
Callback invoked once per visited pixel.
| user_data | Opaque pointer forwarded from the enumerating call. |
| x | Pixel column. |
| y | Pixel row. |
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.
| enum 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.
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.
| enum 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. |
| void bj_circle_pixels | ( | int | cx, |
| int | cy, | ||
| int | radius, | ||
| bj_pixel_fn | callback, | ||
| void * | user_data ) |
| 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).
| bitmap | Target bitmap, or NULL, which draws nothing. |
| cx | X-coordinate of circle centre (pixels). |
| cy | Y-coordinate of circle centre (pixels). |
| radius | Circle radius in pixels; 0 or less draws the centre pixel. |
| color | Pixel value packed in the bitmap's format (see bj_pack_bitmap_rgb). |
| 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.
| bitmap | Target bitmap, or NULL, which draws nothing. |
| cx | X-coordinate of circle centre (pixels). |
| cy | Y-coordinate of circle centre (pixels). |
| radius | Circle radius in pixels; 0 or less draws the centre pixel. |
| color | Pixel value packed in the bitmap's format (see bj_pack_bitmap_rgb). |
Referenced by draw(), draw(), draw(), draw(), on_draw(), and on_draw().
| 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).
| bitmap | The bitmap object, or NULL, which draws nothing. |
| area | The rectangle to draw, or NULL, which draws nothing. |
| pixel | The line pixel value. |
Referenced by draw(), draw(), draw_maze(), fill_cell(), and setup().
| 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.
| bitmap | The bitmap object, or NULL, which draws nothing. |
| x0 | The X coordinate of the first triangle vertex. |
| y0 | The Y coordinate of the first triangle vertex. |
| x1 | The X coordinate of the second triangle vertex. |
| y1 | The Y coordinate of the second triangle vertex. |
| x2 | The X coordinate of the third triangle vertex. |
| y2 | The Y coordinate of the third triangle vertex. |
| color | The fill colour. |
Referenced by draw().
| 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.
| bitmap | The bitmap object, or NULL, which draws nothing. |
| x0 | The X coordinate of the first point in the line. |
| y0 | The Y coordinate of the first point in the line. |
| x1 | The X coordinate of the second point in the line. |
| y1 | The Y coordinate of the second point in the line. |
| pixel | The 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.
Referenced by draw(), draw(), draw_grid_lines(), and draw_maze().
| 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.
| bitmap | The bitmap object, or NULL, which draws nothing. |
| x0 | The X coordinate of the first point in the line. |
| y0 | The Y coordinate of the first point in the line. |
| x1 | The X coordinate of the second point in the line. |
| y1 | The Y coordinate of the second point in the line. |
| mode | Which pixels the line claims (see bj_line_mode). |
| pixel | The 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.
Referenced by draw().
| 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.
| bitmap | Target bitmap, or NULL, which draws nothing. |
| x | Pointer to array of x coordinates (length >= count), or NULL, which draws nothing. |
| y | Pointer to array of y coordinates (length >= count), or NULL, which draws nothing. |
| count | Number of vertices. Segments drawn for i = 0..count-2. |
| end | BJ_POLYLINE_END_OPEN or BJ_POLYLINE_END_CLOSED. |
| color | Pixel 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.
Referenced by draw().
| 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.
| bitmap | Target bitmap, or NULL, which draws nothing. |
| x | Pointer to array of x coordinates (length >= count), or NULL, which draws nothing. |
| y | Pointer to array of y coordinates (length >= count), or NULL, which draws nothing. |
| count | Number of vertices. Segments drawn for i = 0..count-2. |
| end | BJ_POLYLINE_END_OPEN or BJ_POLYLINE_END_CLOSED. |
| mode | Which pixels each segment claims (see bj_line_mode). |
| color | Pixel value packed in the bitmap's format (see bj_pack_bitmap_rgb). |
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.
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.
| bitmap | The bitmap object, or NULL, which draws nothing. |
| area | The rectangle to draw, or NULL, which draws nothing. |
| pixel | The line pixel value. |
| 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.
| bitmap | The bitmap object, or NULL, which draws nothing. |
| x0 | The X coordinate of the first triangle vertex. |
| y0 | The Y coordinate of the first triangle vertex. |
| x1 | The X coordinate of the second triangle vertex. |
| y1 | The Y coordinate of the second triangle vertex. |
| x2 | The X coordinate of the third triangle vertex. |
| y2 | The Y coordinate of the third triangle vertex. |
| color | The line colour. |
Referenced by draw().
| 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.
| cx | Centre, X coordinate. |
| cy | Centre, Y coordinate. |
| radius | Radius in pixels. A radius of 0 or less reports the centre pixel alone. |
| callback | Invoked once per pixel. Does nothing when 0. |
| user_data | Passed 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.
| 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.
| x0 | Ray origin, X coordinate, in cell units. |
| y0 | Ray origin, Y coordinate, in cell units. |
| x1 | Ray end, X coordinate, in cell units. |
| y1 | Ray end, Y coordinate, in cell units. |
| callback | Invoked once per cell entered. Does nothing when 0. |
| user_data | Passed 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.
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.
Referenced by draw().
| 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.
| x0 | First point, X coordinate. |
| y0 | First point, Y coordinate. |
| x1 | Second point, X coordinate. |
| y1 | Second point, Y coordinate. |
| callback | Invoked once per pixel. Does nothing when 0. |
| user_data | Passed 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.
Referenced by draw().
| void bj_grid_ray_cells | ( | bj_real | x0, |
| bj_real | y0, | ||
| bj_real | x1, | ||
| bj_real | y1, | ||
| bj_cell_fn | callback, | ||
| void * | user_data ) |
| void bj_line_pixels | ( | int | x0, |
| int | y0, | ||
| int | x1, | ||
| int | y1, | ||
| bj_pixel_fn | callback, | ||
| void * | user_data ) |