API Documentation

IMPORTANT: The following documentation doesn't reflect current version of Punity and is incomplete. For more detailed information see punity.h.

Memory

Virtual memory (low-level)

void *virtual_reserve(void* ptr, u32 size)

Reserves virtual memory of given size. If pointer ptr is not 0, it'll try to allocate the memory at given address. Reserve is protected with ASSERT. The reserved memory cannot be used, you need to call virtual_commit to be able to use it.

void *virtual_commit(void *ptr, u32 size)

Marks a portion of reserved memory (see virtual_reserve) of given size (lower or equal to reserved size) for use.

void virtual_decommit(void *ptr, u32 size)

Marks a portion of commited memory (see virtual_commit) of given size as not used (but still reserved).

void virtual_free(void *ptr, u32 size)

Releases memory.

void *virtual_alloc(void* ptr, u32 size)

A convenience function to reserve and commit memory.

Memory banks

Memory banks are simple linear pre-allocated pieces of memory with LIFO (last-in first-out) access. Bank is a simple structure containing pointers to the begin and end of the allocated memory. On top of that it also holds a pointer to a push/pop cursor called it. When the application starts, you allocate the bank with bank_init and then you call bank_push and bank_pop to add and remove blocks to and from the bank's cursor.

If there's not enough memory available in the bank, the bank_push will quit the application with a message. This behavior forces you to know how much memory you need for your game. The simple solution is usually just to increment the size of the memory and rebuild the game.

You can also use BankState and it's bank_begin and bank_end functions to store and restore the state of the bank. This is useful if you do multiple push calls and want to reset the bank`s pointer to it's original state when you're done.

Bank bank;
bank_init(&bank, megabytes(16));

BankState state = bank_begin(&bank);
ptr1 = bank_push(&bank, kilobytes(1));
ptr2 = bank_push(&bank, kilobytes(1));
ptr3 = bank_push(&bank, kilobytes(1));

// Pop all of the stuff at once.
bank_end(&state);

Punity defines two default banks:

• CORE->stack is a bank for short-term allocations. The push and pop has to be balanced so when the frame ends it nothing will be allocated in the memory.
• CORE->storage is a memory that is used for long-term allocations of bitmaps, sounds, maps, state, etc.

Banks can be used in various ways. My favorite is to allocate, process and return big memory blocks from a function through CORE->stack:

void *generate_naked_woman() {
    void *ptr = bank_push(CORE->stack, megabytes(1));
    // Generate naked woman bitmap.
    return ptr;
}

void *naked_woman = generate_naked_woman();
// Draw naked woman.
bank_pop(naked_woman);

void bank_init(Bank *bank, u32 capacity)

Intializes an memory bank with given capacity.

void bank_clear(Bank *bank);

Resets the push pointer to zero, but keeps the memory.

void *bank_push(Bank *bank, u32 size)

Pushes a block of given size to current pointer (and return pointer to it) and sets the pointer to the end of that block.

void bank_pop(Bank *bank, void *ptr)

Moves the banks pointer back to ptr.

BankState bank_begin(Bank *bank)

Stores and returns the state of the bank.

void bank_end(BankState *state)

Restores the state of the state.bank to the state when the bank_begin was called.

File I/O

File I/O provides two convenience functions to read and write binary files.

void *file_read(Bank *bank, const char *path, size_t *size)

Reads binary file and adds it to bank. The data should be freed with bank_pop. If bank is 0, then it'll use malloc to allocate the memory and the data should be freed with free.

bool file_write(const char *path, void *ptr, size_t size)

Writes memory block at ptr of given size to the file at path.

Graphics

Color

Color is a struct holding 8-bits per red, green, blue and alpha channels. The ordering of the channels is platform specific and can be customized with PUN_COLOR_CHANNELS. This ordering is used to skip the step of reshifting each color when blitting to screen. This functionality will probably change when platform support emerge.

Punity uses 8-bit indexed colors with palette stored in CORE->canvas.palette, each entry in the palette is Color. In the palette 3 colors indexes are considered special:

• 0 is used for transparent color (r=0, g=0, b=0, a=0) and is reserved; internal algorithms count with this setup.
• 1 is used for black color (r=0, g=0, b=0, a=255) it's recommended but not used internally.
• 2 is used for white color (r=255, g=255, b=255, a=255) it's recommended but not used internally.

Color color_make(u8 r, u8 g, u8 b, u8 a)

Sets up a color struct.

Color color_lerp(Color from, Color to, f32 t)

Returns new color that is in distance t (0..1) between from and to colors.

Rect

A struct holding 4 integer coordinates of an axis-aligned rectangle.

Rect rect_make(i32 min_x, i32 min_y, i32 max_x, i32 max_y)

Rect rect_make_size(i32 x, i32 y, i32 w, i32 h)

Rect rect_make_centered(i32 x, i32 y, i32 w, i32 h)

bool rect_contains_point(Rect *rect, i32 x, i32 y)

rect_tr(r, tx, ty)

rect_width(r)

rect_height(r)

Bitmap

void bitmap_init(Bitmap *bitmap, i32 width, i32 height, void *pixels, int type)

void bitmap_clear(Bitmap *bitmap, u8 color)

void bitmap_save_raw(Bitmap *bitmap, FILE *file)

Not implemented yet.

void bitmap_load_raw(Bitmap *bitmap, FILE *file)

Not implemented yet.

void bitmap_load(Bitmap *bitmap, const char *path)

Requires stb_image.h

void bitmap_load_resource(Bitmap *bitmap, const char *resource_name)

Requires stb_image.h

Canvas

void canvas_clear(u8 color)

void clip_set(Rect rect)

void clip_reset()

bool clip_check()

Drawing

void rect_draw(Rect rect, u8 color)

void rect_draw_push(Rect rect, u8 color, i32 z)

void bitmap_draw(Bitmap *bitmap, i32 x, i32 y, i32 pivot_x, i32 pivot_y, Rect *bitmap_rect, u32 flags, u8 color)

void bitmap_draw(Bitmap *bitmap, i32 x, i32 y, i32 pivot_x, i32 pivot_y, Rect *bitmap_rect, u32 flags, u8 color, i32 z)

void text_draw(const char *text, i32 x, i32 y, u8 color)

void text_draw_push(const char *text, i32 x, i32 y, u8 color, i32 z)