Banjo API 1.1.0-alpha
Low-level C99 game development API
Loading...
Searching...
No Matches
stream_custom.c

Custom sources: plug your own bytes into the stream API.

Custom sources: plug your own bytes into the stream API.Archives, decompressors, encrypted assets: when the bytes come from somewhere Banjo does not know, give it a table of functions. Every stream function then works on your source: the byte-order readers, views when it can seek, and the loaders that take a stream, such as bj_create_bitmap_from_stream.

This example writes a source that unscrambles another stream as it reads: each byte is XORed with a key. It cannot seek, so it leaves seek and size out, and the stream says so.

What you'll learn

#include <banjo/log.h>
#include <banjo/main.h>
#include <banjo/stream.h>
#include <stdint.h>
// The source's state, handed to every function as user_data.
struct scrambled {
bj_stream* inner; // where the scrambled bytes come from
uint8_t key;
};
static size_t scrambled_read(void* buffer, size_t count, void* user_data, enum bj_stream_status* status) {
struct scrambled* source = (struct scrambled*)user_data;
uint8_t* bytes = (uint8_t*)buffer;
const size_t got = bj_read_stream(source->inner, bytes, count);
for (size_t i = 0; i < got; ++i) {
bytes[i] ^= source->key;
}
// Returning fewer bytes is fine: the stream asks again. Returning 0
// with the status left OK means the end of the data; pass an error on.
if (got < count && bj_stream_status(source->inner) != BJ_STREAM_STATUS_END) {
}
return got;
}
// Read-only, unseekable: everything but read stays 0. A static table
// can serve every stream of this kind, since the stream copies it.
scrambled_read, // read
0, // write: the source never writes
0, // seek: nor seeks...
0, // size: ...so the stream cannot seek either
0, // flush
0, // close: the inner stream stays the caller's
};
int main(int argc, char* argv[]) {
(void)argc; (void)argv;
// "Hello, stream!" XORed with 0x2A, as an asset packer would store it,
// followed by a big-endian 2026 scrambled the same way.
static const uint8_t asset[] = {
0x62, 0x4F, 0x46, 0x46, 0x45, 0x06, 0x0A, 0x59, 0x5E, 0x58, 0x4F, 0x4B, 0x47, 0x0B,
0x2D, 0xC0,
};
bj_stream* inner = bj_create_stream_from_read_memory(asset, sizeof(asset));
struct scrambled source = { inner, 0x2A };
bj_error* error = 0;
if (stream == 0) {
bj_err("Cannot create the stream: %s", bj_error_message(error));
bj_clear_error(&error);
return 1;
}
bj_info("Seekable: %s", bj_stream_is_seekable(stream) ? "yes" : "no");
// The stream functions read through the source, unscrambled.
char text[15] = {0};
uint16_t year = 0;
if (bj_read_stream(stream, text, 14) == 14 && bj_read_stream_u16_be(stream, &year)) {
bj_info("\"%s\", %u", text, (unsigned)year);
}
return 0;
}
struct bj_stream bj_stream
Definition api.h:374
struct bj_error bj_error
Definition api.h:348
const char * bj_error_message(const struct bj_error *error)
Gets the error message from an error object.
void bj_clear_error(struct bj_error **error)
Frees an error and sets the pointer to NULL.
#define bj_info(...)
Log a message using the BJ_LOG_INFO level.
Definition log.h:141
#define bj_err(...)
Log a message using the BJ_LOG_ERROR level.
Definition log.h:169
void bj_destroy_stream(struct bj_stream *stream)
Destroy a stream and release its memory.
bj_bool bj_read_stream_u16_be(struct bj_stream *stream, uint16_t *value)
Reads a big-endian uint16_t.
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.
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.
bj_bool bj_stream_is_seekable(const struct bj_stream *stream)
Whether the stream can move its cursor.
bj_stream_status
Why the last read or write of a stream fell short.
Definition stream.h:150
size_t bj_read_stream(struct bj_stream *stream, void *dest, size_t count)
Reads data from the stream into a destination buffer.
@ BJ_STREAM_READ
The stream reads.
Definition stream.h:130
@ BJ_STREAM_STATUS_END
The data ran out, or a fixed-size stream is full.
Definition stream.h:152
@ BJ_STREAM_STATUS_ERROR
The source failed.
Definition stream.h:154
The functions of a source the program supplies.
Definition stream.h:257
Logging utility functions.
Portable main() replacement with platform-aware entry shim.
Header file for struct bj_stream struct and related functions.
uint8_t key
bj_stream * inner
static size_t scrambled_read(void *buffer, size_t count, void *user_data, enum bj_stream_status *status)
static const struct bj_stream_callbacks scrambled_callbacks
int main(void)