|
Banjo API 1.1.0-alpha
Low-level C99 game development API
|
Data Structures | |
| struct | bj_stream_callbacks |
Macros | |
| #define | bj_stream_read_t(stream, type, buffer) |
| #define | bj_stream_skip_t(stream, type) |
Typedefs | |
| typedef enum bj_seek_origin | bj_seek_origin |
| typedef enum bj_stream_flag | bj_stream_flag |
| typedef size_t(* | bj_stream_read_fn) (void *buffer, size_t count, void *user_data, enum bj_stream_status *status) |
| typedef size_t(* | bj_stream_write_fn) (const void *data, size_t count, void *user_data, enum bj_stream_status *status) |
| typedef bj_bool(* | bj_stream_seek_fn) (size_t position, void *user_data) |
| typedef size_t(* | bj_stream_size_fn) (void *user_data) |
| typedef bj_bool(* | bj_stream_flush_fn) (void *user_data) |
| typedef void(* | bj_stream_close_fn) (void *user_data) |
Enumerations | |
| enum | bj_seek_origin { BJ_SEEK_BEGIN = 0x00 , BJ_SEEK_CURRENT = 0x01 , BJ_SEEK_END = 0x02 } |
| enum | bj_stream_flag { BJ_STREAM_READ = 0x01 , BJ_STREAM_WRITE = 0x02 , BJ_STREAM_APPEND = 0x04 , BJ_STREAM_TRUNCATE = 0x08 , BJ_STREAM_CREATE = 0x10 , BJ_STREAM_EXCLUSIVE = 0x20 , BJ_STREAM_READ_WRITE = BJ_STREAM_READ | BJ_STREAM_WRITE } |
| enum | bj_stream_status { BJ_STREAM_STATUS_OK = 0 , BJ_STREAM_STATUS_END = 1 , BJ_STREAM_STATUS_NOT_READY = 2 , BJ_STREAM_STATUS_ERROR = 3 , BJ_STREAM_STATUS_READ_ONLY = 4 , BJ_STREAM_STATUS_WRITE_ONLY = 5 , BJ_STREAM_STATUS_LOCKED = 6 } |
Functions | |
| struct bj_stream * | bj_create_stream (void) |
| struct bj_stream * | bj_allocate_stream (void) |
| struct bj_stream * | bj_create_stream_from_read_memory (const void *data, size_t length) |
| struct bj_stream * | bj_open_stream_read (const void *data, size_t length) |
| struct bj_stream * | bj_create_stream_from_memory (void *data, size_t length, uint32_t flags) |
| struct bj_stream * | bj_create_stream_from_path (struct bj_str path, uint32_t flags, struct bj_error **error) |
| struct bj_stream * | bj_open_stream_file (const char *path, struct bj_error **error) |
| struct bj_stream * | bj_create_stream_from_callbacks (const struct bj_stream_callbacks *callbacks, uint32_t flags, void *user_data, struct bj_error **error) |
| struct bj_stream * | bj_create_stream_span (struct bj_stream *parent, size_t offset, size_t length) |
| void | bj_destroy_stream (struct bj_stream *stream) |
| void | bj_close_stream (struct bj_stream *stream) |
| size_t | bj_read_stream (struct bj_stream *stream, void *dest, size_t count) |
| size_t | bj_write_stream (struct bj_stream *stream, const void *data, size_t count) |
| bj_bool | bj_flush_stream (struct bj_stream *stream) |
| size_t | bj_stream_length (struct bj_stream *stream) |
| size_t | bj_get_stream_length (struct bj_stream *stream) |
| size_t | bj_seek_stream (struct bj_stream *stream, ptrdiff_t position, enum bj_seek_origin from) |
| size_t | bj_stream_position (struct bj_stream *stream) |
| size_t | bj_tell_stream (struct bj_stream *stream) |
| const void * | bj_stream_peek (struct bj_stream *stream, size_t offset, size_t length) |
| enum bj_stream_status | bj_stream_status (const struct bj_stream *stream) |
| void | bj_clear_stream_status (struct bj_stream *stream) |
| uint32_t | bj_stream_flags (const struct bj_stream *stream) |
| bj_bool | bj_stream_has_flag (const struct bj_stream *stream, enum bj_stream_flag flag) |
| bj_bool | bj_stream_is_seekable (const struct bj_stream *stream) |
| bj_bool | bj_stream_is_mapped (const struct bj_stream *stream) |
Byte-order reads and writes | |
Each reader takes the bytes of one integer at the cursor and decodes them in the order its name gives, _le for little-endian and _be for big-endian, whatever the order of the computer. Signed integers are in two's complement. It gives BJ_TRUE when all the bytes were there. Else BJ_FALSE, with the destination left as it was, the bytes that were left consumed, and the reason in bj_stream_status. A 0 destination skips the integer. Each writer stores one integer at the cursor in the order its name gives, and gives BJ_TRUE when all its bytes went through. A 0 stream gives BJ_FALSE. | |
| bj_bool | bj_read_stream_u8 (struct bj_stream *stream, uint8_t *value) |
| bj_bool | bj_read_stream_i8 (struct bj_stream *stream, int8_t *value) |
| bj_bool | bj_read_stream_u16_le (struct bj_stream *stream, uint16_t *value) |
| bj_bool | bj_read_stream_u16_be (struct bj_stream *stream, uint16_t *value) |
| bj_bool | bj_read_stream_i16_le (struct bj_stream *stream, int16_t *value) |
| bj_bool | bj_read_stream_i16_be (struct bj_stream *stream, int16_t *value) |
| bj_bool | bj_read_stream_u32_le (struct bj_stream *stream, uint32_t *value) |
| bj_bool | bj_read_stream_u32_be (struct bj_stream *stream, uint32_t *value) |
| bj_bool | bj_read_stream_i32_le (struct bj_stream *stream, int32_t *value) |
| bj_bool | bj_read_stream_i32_be (struct bj_stream *stream, int32_t *value) |
| bj_bool | bj_read_stream_u64_le (struct bj_stream *stream, uint64_t *value) |
| bj_bool | bj_read_stream_u64_be (struct bj_stream *stream, uint64_t *value) |
| bj_bool | bj_read_stream_i64_le (struct bj_stream *stream, int64_t *value) |
| bj_bool | bj_read_stream_i64_be (struct bj_stream *stream, int64_t *value) |
| bj_bool | bj_write_stream_u8 (struct bj_stream *stream, uint8_t value) |
| bj_bool | bj_write_stream_i8 (struct bj_stream *stream, int8_t value) |
| bj_bool | bj_write_stream_u16_le (struct bj_stream *stream, uint16_t value) |
| bj_bool | bj_write_stream_u16_be (struct bj_stream *stream, uint16_t value) |
| bj_bool | bj_write_stream_i16_le (struct bj_stream *stream, int16_t value) |
| bj_bool | bj_write_stream_i16_be (struct bj_stream *stream, int16_t value) |
| bj_bool | bj_write_stream_u32_le (struct bj_stream *stream, uint32_t value) |
| bj_bool | bj_write_stream_u32_be (struct bj_stream *stream, uint32_t value) |
| bj_bool | bj_write_stream_i32_le (struct bj_stream *stream, int32_t value) |
| bj_bool | bj_write_stream_i32_be (struct bj_stream *stream, int32_t value) |
| bj_bool | bj_write_stream_u64_le (struct bj_stream *stream, uint64_t value) |
| bj_bool | bj_write_stream_u64_be (struct bj_stream *stream, uint64_t value) |
| bj_bool | bj_write_stream_i64_le (struct bj_stream *stream, int64_t value) |
| bj_bool | bj_write_stream_i64_be (struct bj_stream *stream, int64_t value) |
Read and write bytes through one API, whatever holds them: memory, a file, a network connection, the caller's own functions, or a range of another stream.
A stream is a moving cursor over a sequence of bytes. The caller iteratively asks for N bytes, moving the cursor ahead until we reach the end. The API is similar to the standard C FILE* handle, with the exception that a stream initialisation abstract away several possible sources of data: file, network, memory buffer or custom sources. This abstraction allows any user code to operate on streamed data without any knowledge about the originating source of the data.
| Constructor | Bytes |
|---|---|
| bj_create_stream | memory the stream owns and grows |
| bj_create_stream_from_read_memory | a caller buffer, read-only, not copied |
| bj_create_stream_from_memory | a caller buffer, in place, never grows |
| bj_create_stream_from_path | a file, read and written on demand |
| bj_create_stream_from_callbacks | the program's functions (archives, codecs…) |
| bj_create_stream_span | a range of another stream, a span |
| bj_create_stream_from_tcp | a TCP connection, see net.h |
Whatever the source, release the stream with bj_destroy_stream.
A stream reads when its flags hold BJ_STREAM_READ and writes when they hold BJ_STREAM_WRITE. Both together are BJ_STREAM_READ_WRITE. Files take four more, which combine as the modes of fopen do:
| fopen | Flags |
|---|---|
| "r" | BJ_STREAM_READ |
| "r+" | BJ_STREAM_READ_WRITE |
| "w" | BJ_STREAM_WRITE \| BJ_STREAM_CREATE \| BJ_STREAM_TRUNCATE |
| "a" | BJ_STREAM_WRITE \| BJ_STREAM_CREATE \| BJ_STREAM_APPEND |
| "wx" | BJ_STREAM_WRITE \| BJ_STREAM_CREATE \| BJ_STREAM_EXCLUSIVE |
bj_stream_flags and bj_stream_has_flag give the flags back.
Whether a stream can move its cursor, and whether a file is mapped into memory, depends on the source. The functions bj_stream_is_seekable and bj_stream_is_mapped query for these capabilities. For example, a TCP connection cannot seek.
A read or a write returns how many bytes it moved. The byte-order functions (such as bj_read_stream_u32_le) return BJ_TRUE only when the whole integer went through, whatever the byte order of the computer running the program.
When a count falls short, bj_stream_status says why:
bj_seek_stream moves the cursor. bj_stream_position tells where it currently is. bj_stream_length tells the total size of the data.
Seeking past either end doesn't fail. It clamps to the boundary.
bj_create_stream_span turns a range of an existing stream into a new, independent stream. This span cannot reach data outside of the given range.
A stream belongs to one thread at a time.
| struct bj_stream_callbacks |
The functions of a source the program supplies.
Each function receives the user_data given to bj_create_stream_from_callbacks.
It is possible to set 0 to some of the function pointers:
The stream copies this table, so it can live on the stack, or be one static const table shared by every stream of the program.
| Data Fields | ||
|---|---|---|
| bj_stream_close_fn | close | Releases the source, or 0. |
| bj_stream_flush_fn | flush | Flushes, or 0. |
| bj_stream_read_fn | read | Reads bytes, or 0. |
| bj_stream_seek_fn | seek | Moves the source's cursor, or 0. |
| bj_stream_size_fn | size | Gives the size, or 0. |
| bj_stream_write_fn | write | Writes bytes, or 0. |
| #define bj_stream_read_t | ( | stream, | |
| type, | |||
| buffer ) |
Reads data of a specified type from the stream into a buffer.
The value is in the byte order of the computer running the program. For a file format, prefer the byte-order readers such as bj_read_stream_u32_le.
| stream | Pointer to the stream instance. |
| type | Data type to read. |
| buffer | Pointer to the buffer to store the read data. |
| #define bj_stream_skip_t | ( | stream, | |
| type ) |
Skips bytes of a specified type from the stream.
| stream | Pointer to the stream instance. |
| type | Data type to skip. |
| typedef enum bj_seek_origin bj_seek_origin |
| typedef void(* bj_stream_close_fn) (void *user_data) |
Releases the source, once, when the stream is destroyed.
| user_data | The pointer given to bj_create_stream_from_callbacks. |
| typedef enum bj_stream_flag bj_stream_flag |
| typedef bj_bool(* bj_stream_flush_fn) (void *user_data) |
Pushes the bytes the source holds back to where they go.
| user_data | The pointer given to bj_create_stream_from_callbacks. |
| typedef size_t(* bj_stream_read_fn) (void *buffer, size_t count, void *user_data, enum bj_stream_status *status) |
Moves up to count bytes from the source into buffer.
| buffer | Where to put the bytes, never 0. |
| count | How many bytes the stream wants, never 0. |
| user_data | The pointer given to bj_create_stream_from_callbacks. |
| status | Set to BJ_STREAM_STATUS_OK on entry. Set it to say why fewer bytes came, or leave it to mean the end. |
count. The stream calls again until it has count, so returning fewer is fine. | typedef bj_bool(* bj_stream_seek_fn) (size_t position, void *user_data) |
Moves the source's cursor to an absolute position.
The stream keeps its own cursor and calls this only when the source must move before a transfer.
| position | Where the source must stand. |
| user_data | The pointer given to bj_create_stream_from_callbacks. |
position. | typedef size_t(* bj_stream_size_fn) (void *user_data) |
Gives the current size of the source, in bytes.
| user_data | The pointer given to bj_create_stream_from_callbacks. |
| typedef size_t(* bj_stream_write_fn) (const void *data, size_t count, void *user_data, enum bj_stream_status *status) |
Moves up to count bytes from data into the source.
| data | The bytes to write, never 0. |
| count | How many bytes to write, never 0. |
| user_data | The pointer given to bj_create_stream_from_callbacks. |
| status | Set to BJ_STREAM_STATUS_OK on entry. Set it to say why fewer bytes went, or leave it to mean an error. |
count. | enum bj_seek_origin |
| enum bj_stream_flag |
What a stream is opened for, combined with |.
BJ_STREAM_READ and BJ_STREAM_WRITE apply to every source. The four others only mean something to bj_create_stream_from_path.
| enum bj_stream_status |
Why the last read or write of a stream fell short.
END and NOT_READY are soft: a seek clears them. ERROR, READ_ONLY and WRITE_ONLY are hard: they replace a soft status, and stay until bj_clear_stream_status. The status never stops an operation: it only reports.
| Enumerator | |
|---|---|
| BJ_STREAM_STATUS_OK | Nothing fell short. |
| BJ_STREAM_STATUS_END | The data ran out, or a fixed-size stream is full. |
| BJ_STREAM_STATUS_NOT_READY | The source could not answer yet, such as a socket whose timeout expired. |
| BJ_STREAM_STATUS_ERROR | The source failed. |
| BJ_STREAM_STATUS_READ_ONLY | A write on a stream without BJ_STREAM_WRITE. |
| BJ_STREAM_STATUS_WRITE_ONLY | A read on a stream without BJ_STREAM_READ. |
| BJ_STREAM_STATUS_LOCKED | A transfer on a stream held by a bj_text_wrapper, which is the only reader and writer while it lives. |
| struct bj_stream * bj_allocate_stream | ( | void | ) |
| void bj_clear_stream_status | ( | struct bj_stream * | stream | ) |
Sets the status back to BJ_STREAM_STATUS_OK.
| stream | The stream, or 0, which does nothing. |
| void bj_close_stream | ( | struct bj_stream * | stream | ) |
| struct bj_stream * bj_create_stream | ( | void | ) |
Create an empty stream in memory, which reads and writes, and grows as it is written.
The stream owns its bytes; bj_stream_peek gives them back.
The caller owns the stream and must release it with bj_destroy_stream.
| struct bj_stream * bj_create_stream_from_callbacks | ( | const struct bj_stream_callbacks * | callbacks, |
| uint32_t | flags, | ||
| void * | user_data, | ||
| struct bj_error ** | error ) |
Create a stream over a source the program supplies.
| callbacks | The source's functions, copied. 0 gives 0 and leaves error alone. |
| flags | BJ_STREAM_READ, BJ_STREAM_WRITE or BJ_STREAM_READ_WRITE. |
| user_data | Handed to every function, unchanged. |
| error | Optional error location. |
user_data stays the caller's. Referenced by main().
| struct bj_stream * bj_create_stream_from_memory | ( | void * | data, |
| size_t | length, | ||
| uint32_t | flags ) |
Create a stream that reads and writes the caller's buffer in place.
The bytes are not copied, and the buffer must outlive the stream. Its length is length from the start, and it never grows: a write that reaches the end stops there, with BJ_STREAM_STATUS_END.
| data | The buffer, or 0, which gives 0 unless length is 0. |
| length | The size of the buffer, in bytes. |
| flags | BJ_STREAM_READ, BJ_STREAM_WRITE or BJ_STREAM_READ_WRITE. Anything else gives 0. |
| struct bj_stream * bj_create_stream_from_path | ( | struct bj_str | path, |
| uint32_t | flags, | ||
| struct bj_error ** | error ) |
Create a stream that reads, writes or creates a file.
| path | The path, in UTF-8. |
| flags | A combination of bj_stream_flag; see the Flags section. |
| error | Optional error location. |
Instead of being loaded entirely, the file is read and written on demand. It stays open until the stream is destroyed. A non-empty file opened with BJ_STREAM_READ alone is mapped into memory where the platform allows it, so the system pages in only what is read (see bj_stream_is_mapped). On POSIX systems, a mapped file that another program truncates raises SIGBUS when the missing bytes are read.
Referenced by main(), and write_text().
| struct bj_stream * bj_create_stream_from_read_memory | ( | const void * | data, |
| size_t | length ) |
Create a read-only stream that reads from an in-memory buffer.
The bytes are not copied: the stream reads from data directly, so the buffer must outlive the stream. The stream cannot write.
| data | Pointer to the data buffer, or 0, which gives 0 unless length is 0. |
| length | Length of the data buffer in bytes. |
Referenced by main().
| struct bj_stream * bj_create_stream_span | ( | struct bj_stream * | parent, |
| size_t | offset, | ||
| size_t | length ) |
Create a span over the range [offset, offset + length) of another stream.
The span checks its range once, here, and from then on cannot read, write, skip or peek outside it. It has its own cursor, at 0, and its own status. It never moves the parent's cursor nor changes its status. It takes the parent's BJ_STREAM_READ and BJ_STREAM_WRITE, except WRITE when the parent appends, and it never grows.
The span borrows parent: destroy every span before its parent.
| parent | The stream to span, or 0, which gives 0. A parent that cannot seek gives 0 too. |
| offset | Where the range starts in the parent. |
| length | How many bytes the range holds. |
Referenced by main().
| void bj_destroy_stream | ( | struct bj_stream * | stream | ) |
Destroy a stream and release its memory.
A file stream closes its file. A custom source gets its close call.
| stream | The stream to destroy. 0 is ignored. |
Referenced by main(), main(), and write_text().
Pushes what the stream wrote to where it goes.
Memory streams and files have nothing held back, and succeed. A custom source gets its flush call.
| stream | The stream, or 0, which gives BJ_FALSE. |
| size_t bj_get_stream_length | ( | struct bj_stream * | stream | ) |
| struct bj_stream * bj_open_stream_read | ( | const void * | data, |
| size_t | length ) |
| size_t bj_read_stream | ( | struct bj_stream * | stream, |
| void * | dest, | ||
| size_t | count ) |
Reads data from the stream into a destination buffer.
| stream | Pointer to the stream instance, or 0, which reads 0 bytes. |
| dest | Pointer to the destination buffer, or 0 to skip the bytes, as bj_stream_skip_t does. |
| count | Number of bytes to read. |
The function advances the stream position by the bytes it read. It keeps asking the source until it has count bytes. When it returns fewer, bj_stream_status says why: BJ_STREAM_STATUS_END when the data ran out, BJ_STREAM_STATUS_WRITE_ONLY for a stream without BJ_STREAM_READ, and so on.
This function does not perform any memory bounds checking. It is the caller's responsibility to ensure dest has enough space to hold count bytes.
Referenced by main(), and scrambled_read().
Reads a big-endian int16_t.
Reads a big-endian int32_t.
Reads a little-endian int32_t.
Reads a big-endian int64_t.
Reads a little-endian int64_t.
Reads a big-endian uint64_t.
Reads a little-endian uint64_t.
| size_t bj_seek_stream | ( | struct bj_stream * | stream, |
| ptrdiff_t | position, | ||
| enum bj_seek_origin | from ) |
Seeks to a new position in the stream relative to a specified origin.
| stream | Pointer to the stream instance, or 0, which gives 0. |
| position | Offset for the new position. |
| from | Origin relative to which the position should be calculated. Another value leaves the cursor where it is. |
The function clamps the new position to stay within the valid range of the stream, from 0 to the length of the stream, without overflowing, and clears a BJ_STREAM_STATUS_END or BJ_STREAM_STATUS_NOT_READY status. A stream that cannot seek leaves its cursor and status where they are; see bj_stream_is_seekable.
| uint32_t bj_stream_flags | ( | const struct bj_stream * | stream | ) |
The flags the stream was created with.
| stream | The stream, or 0, which gives 0. |
| bj_bool bj_stream_has_flag | ( | const struct bj_stream * | stream, |
| enum bj_stream_flag | flag ) |
Whether the stream was created with one flag.
| stream | The stream, or 0, which gives BJ_FALSE. |
| flag | One bj_stream_flag; 0 gives BJ_FALSE. |
flag is set. Whether the stream reads a file mapped into memory.
A non-empty file opened with BJ_STREAM_READ alone is mapped where the platform allows it, and so is a span of such a file.
| stream | The stream, or 0, which gives BJ_FALSE. |
Referenced by main().
Whether the stream can move its cursor.
Memory streams, files and spans can. A TCP stream cannot, nor a custom source without both seek and size.
| stream | The stream, or 0, which gives BJ_FALSE. |
Referenced by main().
| size_t bj_stream_length | ( | struct bj_stream * | stream | ) |
Return the total size of the stream, in bytes.
| stream | Pointer to the stream instance, or 0, which gives 0. |
| const void * bj_stream_peek | ( | struct bj_stream * | stream, |
| size_t | offset, | ||
| size_t | length ) |
Points at bytes of the stream without moving the cursor.
The bounds are checked here, once: the result is 0 rather than a pointer past the data. Memory streams, mapped files and spans over them point into their own bytes. Other streams copy into a buffer of their own.
| stream | The stream, or 0, which gives 0. |
| offset | Where the bytes start, from the beginning of the stream. |
| length | How many bytes, 0 giving 0. |
length bytes, valid until the next call that takes this stream, or its destruction, or 0 when the range is outside the stream, the stream cannot seek, or lacks BJ_STREAM_READ, which also records BJ_STREAM_STATUS_WRITE_ONLY. Referenced by main().
| size_t bj_stream_position | ( | struct bj_stream * | stream | ) |
Return the current cursor position within the stream.
| stream | Pointer to the stream instance, or 0, which gives 0. |
Referenced by main().
| enum bj_stream_status bj_stream_status | ( | const struct bj_stream * | stream | ) |
Why the last read or write fell short, sticky until cleared.
| stream | The stream, or 0, which gives BJ_STREAM_STATUS_ERROR. |
| size_t bj_tell_stream | ( | struct bj_stream * | stream | ) |
| size_t bj_write_stream | ( | struct bj_stream * | stream, |
| const void * | data, | ||
| size_t | count ) |
Writes bytes at the cursor, over those already there.
The cursor advances past the bytes written. A growable stream, a file and a custom source grow when written past their end. A buffer stream and a span stop at theirs, with BJ_STREAM_STATUS_END. A file opened with BJ_STREAM_APPEND writes at its end, wherever the cursor stood.
| stream | The stream, or 0, which writes 0 bytes. |
| data | The bytes, or 0, which writes 0 bytes. |
| count | How many bytes to write. |
count means bj_stream_status says why, such as BJ_STREAM_STATUS_READ_ONLY for a stream without BJ_STREAM_WRITE. Referenced by write_text().
Writes a big-endian int16_t.
Writes a big-endian int32_t.
Writes a little-endian int32_t.
Writes a big-endian int64_t.
Writes a little-endian int64_t.
Writes a big-endian uint16_t.
Writes a big-endian uint64_t.
Writes a little-endian uint64_t.