QOI Encoder Library for N64. More...

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>
#include <stdlib.h>

Data Structures
struct	qoi_desc_t
	QOI descriptor as read by the header of a QOI file. More...
union	qoi_pixel_t
	QOI pixel structure for storing the color values of a pixel in both individual channels and as a concatenated value for easy comparison and hashing. More...
struct	qoi_enc_t
	QOI encoder structure. More...

Macros
#define	QOI_ALLOW_MEM_ALLOC 1
#define	QOI_ALLOW_MEM_FREE 1
#define	QOI_TAG 0xC0
	Mask for the tag bits of the opcode, which are the two most significant bits of the opcode byte.
#define	QOI_TAG_MASK 0x3F
	Mask for the remaining bits of the opcode after masking out the tag bits.
#define	QOI_OP_RGB 0xFE
	11111110: Followed by 3 bytes of RGB data, representing the color of the pixel. This is used when the pixel value cannot be encoded using any of the other opcodes.
#define	QOI_OP_RGBA 0xFF
	11111110: Followed by 3 bytes of RGB data and 1 byte of alpha data, representing the color of the pixel. This is used when the pixel value cannot be encoded using any of the other opcodes.
#define	QOI_OP_INDEX 0x00
	00xxxxxx: Use the color at the index xx in the color index array.
#define	QOI_OP_DIFF 0x40
	01xxxxxx: The color is the same as the previous pixel, with each channel optionally modified by a small value stored in the remaining 6 bits of the opcode.
#define	QOI_OP_LUMA 0x80
	10xxxxxx: The color is represented by a luminance value and two chroma values.
#define	QOI_OP_RUN 0xC0
	11xxxxxx: The color is the same as the previous pixel, and this run continues for xx pixels.

Enumerations
enum	qoi_pixel_color { QOI_RED , QOI_GREEN , QOI_BLUE , QOI_ALPHA }
enum	qoi_channels { QOI_WHITESPACE = 3 , QOI_TRANSPARENT = 4 }
enum	qoi_colorspace { QOI_SRGB , QOI_LINEAR }

Functions
static uint32_t	qoi_get_be32 (uint32_t value)
	Extract a 32-bit big endian integer regardless of endianness.
static uint32_t	qoi_to_be32 (uint32_t value)
	Write a 32-bit big endian integer regardless of endianness.
void	qoi_set_pixel_rgb (qoi_pixel_t *pixel, uint8_t red, uint8_t green, uint8_t blue)
	Sets the RGB pixel by a certain pixel value.
void	qoi_set_pixel_rgba (qoi_pixel_t *pixel, uint8_t red, uint8_t green, uint8_t blue, uint8_t alpha)
	Sets the RGBA pixel by a certain pixel value including an transparency alpha value.
void	qoi_initalize_pixel (qoi_pixel_t *pixel)
	Initalizes the pixels to the default state.
static bool	qoi_cmp_pixel (qoi_pixel_t pixel1, qoi_pixel_t pixel2, const uint8_t channels)
	Compares two pixels for the same color.
static int32_t	qoi_get_index_position (qoi_pixel_t pixel)
	Hashing function for pixels: up to 64 possible hash values.
bool	qoi_desc_init (qoi_desc_t *desc)
	Initalize the QOI desciptor to the default values.
void	qoi_set_dimensions (qoi_desc_t *desc, uint32_t width, uint32_t height)
	Sets the image dimensions of an image for QOI descriptor.
void	qoi_set_channels (qoi_desc_t *desc, uint8_t channels)
	Sets the amount of channels of an image for QOI descriptor.
void	qoi_set_colorspace (qoi_desc_t *desc, uint8_t colorspace)
	Sets the colorspace of an image for QOI descriptor.
void	write_qoi_header (qoi_desc_t desc, void dest)
	Writes the QOI metadata information to the file.
bool	read_qoi_header (qoi_desc_t desc, void data)
bool	qoi_enc_init (qoi_desc_t desc, qoi_enc_t enc)
	Initalize the QOI encoder to the default state.
bool	qoi_enc_alloc_buffer (qoi_enc_t *enc, uint32_t len, bool shouldFreePrevBuffer)
	Allocates a buffer for the QOI encoder.
bool	qoi_enc_set_buffer (qoi_enc_t enc, void newBuffer, uint32_t len, bool shouldFreePrevBuffer)
	Sets a buffer for the QOI encoder, automatically free if free buffer flag is set.
bool	qoi_enc_free_buffer (qoi_enc_t *enc)
	Frees the buffer allocated for the QOI encoder.
bool	qoi_enc_reset_buffer (qoi_enc_t *enc)
	Resets the buffer of the QOI encoder to the default state.
void	qoi_encode_chunk (qoi_desc_t desc, qoi_enc_t enc, void *qoi_pixel_bytes)
	Encode pixel data into QOI opcodes.
static void	qoi_enc_rgb (qoi_enc_t *enc, qoi_pixel_t px)
	Place the RGB information into the QOI file.
static void	qoi_enc_rgba (qoi_enc_t *enc, qoi_pixel_t px)
	Place the RGBA information into the QOI file.
static void	qoi_enc_index (qoi_enc_t *enc, uint8_t index_pos)
	Place the index position of the buffer into the QOI file.
static void	qoi_enc_diff (qoi_enc_t *enc, uint8_t red_diff, uint8_t green_diff, uint8_t blue_diff)
	Place the differences between color values into the QOI opcode.
static void	qoi_enc_luma (qoi_enc_t *enc, uint8_t green_diff, uint8_t dr_dg, uint8_t db_dg)
	Place the luma values into the QOI opcode.
static void	qoi_enc_run (qoi_enc_t *enc)
	Place the run length of a pixel color information into the QOI opcode.

Variables
static const uint8_t	QOI_MAGIC [4] = {'q', 'o', 'i', 'f'}
	QOI magic number.
static const uint8_t	QOI_PADDING [8] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01}
	QOI end of file padding bytes.

Detailed Description

QOI Encoder Library for N64.

Author: Aftersol

Version: 1.0.1

Date: 2026-05-09

Copyright: (c) 2024-2026 Aftersol

qoi_enc_n64.h - QOI Encoder Library for N64

This header file is modified from Simplified QOI Encoder code for the Nintendo 64. It provides functions to encode the N64 framebuffer into the QOI format. The encoder is designed to be efficient and suitable for the constraints of the N64 hardware.

Simplified QOI Encoder: https://github.com/Aftersol/Simplified-QOI-Codec

QOI Format Website: https://qoiformat.org/ QOI Specification: https://qoiformat.org/qoi-specification.pdf

Code licensed under MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Definition in file qoi_enc_n64.h.

Macro Definition Documentation

◆ QOI_ALLOW_MEM_ALLOC

#define QOI_ALLOW_MEM_ALLOC 1

Definition at line 56 of file qoi_enc_n64.h.

◆ QOI_ALLOW_MEM_FREE

#define QOI_ALLOW_MEM_FREE 1

Definition at line 57 of file qoi_enc_n64.h.

◆ QOI_OP_DIFF

#define QOI_OP_DIFF 0x40

01xxxxxx: The color is the same as the previous pixel, with each channel optionally modified by a small value stored in the remaining 6 bits of the opcode.

Definition at line 77 of file qoi_enc_n64.h.

◆ QOI_OP_INDEX

#define QOI_OP_INDEX 0x00

00xxxxxx: Use the color at the index xx in the color index array.

Definition at line 75 of file qoi_enc_n64.h.

◆ QOI_OP_LUMA

#define QOI_OP_LUMA 0x80

10xxxxxx: The color is represented by a luminance value and two chroma values.

Definition at line 79 of file qoi_enc_n64.h.

◆ QOI_OP_RGB

#define QOI_OP_RGB 0xFE

11111110: Followed by 3 bytes of RGB data, representing the color of the pixel. This is used when the pixel value cannot be encoded using any of the other opcodes.

Definition at line 71 of file qoi_enc_n64.h.

◆ QOI_OP_RGBA

#define QOI_OP_RGBA 0xFF

11111110: Followed by 3 bytes of RGB data and 1 byte of alpha data, representing the color of the pixel. This is used when the pixel value cannot be encoded using any of the other opcodes.

Definition at line 73 of file qoi_enc_n64.h.

◆ QOI_OP_RUN

#define QOI_OP_RUN 0xC0

11xxxxxx: The color is the same as the previous pixel, and this run continues for xx pixels.

Definition at line 81 of file qoi_enc_n64.h.

◆ QOI_TAG

#define QOI_TAG 0xC0

Mask for the tag bits of the opcode, which are the two most significant bits of the opcode byte.

Definition at line 66 of file qoi_enc_n64.h.

◆ QOI_TAG_MASK

#define QOI_TAG_MASK 0x3F

Mask for the remaining bits of the opcode after masking out the tag bits.

Definition at line 68 of file qoi_enc_n64.h.

Enumeration Type Documentation

◆ qoi_channels

enum qoi_channels

Enumerator
QOI_WHITESPACE
QOI_TRANSPARENT

Definition at line 84 of file qoi_enc_n64.h.

◆ qoi_colorspace

enum qoi_colorspace

Enumerator
QOI_SRGB
QOI_LINEAR

Definition at line 85 of file qoi_enc_n64.h.

◆ qoi_pixel_color

enum qoi_pixel_color

Enumerator
QOI_RED
QOI_GREEN
QOI_BLUE
QOI_ALPHA

Definition at line 83 of file qoi_enc_n64.h.

Function Documentation

◆ qoi_cmp_pixel()

bool qoi_cmp_pixel	(	qoi_pixel_t	pixel1,
		qoi_pixel_t	pixel2,
		const uint8_t	channels )

static

Compares two pixels for the same color.

Parameters

pixel1	The first pixel to compare
pixel2	The second pixel to compare
channels	The amount of channels to compare for the pixels (3 for RGB, 4 for RGBA)

Returns: If the two pixels are the same color

Definition at line 244 of file qoi_enc_n64.h.

◆ qoi_desc_init()

bool qoi_desc_init ( qoi_desc_t * desc )

Initalize the QOI desciptor to the default values.

Parameters

desc	QOI descriptor to initialize

Returns: If the descriptor initialized successfully

Definition at line 301 of file qoi_enc_n64.h.

◆ qoi_enc_alloc_buffer()

bool qoi_enc_alloc_buffer	(	qoi_enc_t *	enc,
		uint32_t	len,
		bool	shouldFreePrevBuffer )

Allocates a buffer for the QOI encoder.

Parameters

enc	QOI encoder
len	Length of the buffer to allocate
shouldFreePrevBuffer	if true, free previous buffer

Returns: If the buffer was allocated successfully

Definition at line 601 of file qoi_enc_n64.h.

◆ qoi_enc_diff()

void qoi_enc_diff	(	qoi_enc_t *	enc,
		uint8_t	red_diff,
		uint8_t	green_diff,
		uint8_t	blue_diff )

inlinestatic

Place the differences between color values into the QOI opcode.

Parameters

enc	QOI encoder

Definition at line 400 of file qoi_enc_n64.h.

◆ qoi_enc_free_buffer()

bool qoi_enc_free_buffer ( qoi_enc_t * enc )

Frees the buffer allocated for the QOI encoder.

Parameters

enc	QOI encoder

Returns: If the buffer was freed successfully

Definition at line 630 of file qoi_enc_n64.h.

◆ qoi_enc_index()

void qoi_enc_index	(	qoi_enc_t *	enc,
		uint8_t	index_pos )

inlinestatic

Place the index position of the buffer into the QOI file.

Parameters

enc	QOI encoder
index_pos	The index position of the buffer to place into the QOI opcode

Definition at line 391 of file qoi_enc_n64.h.

◆ qoi_enc_init()

bool qoi_enc_init	(	qoi_desc_t *	desc,
		qoi_enc_t *	enc )

Initalize the QOI encoder to the default state.

Parameters

desc	descriptor of the QOI file
enc	QOI encoder

Returns: If the encoder initialized successfully

Definition at line 537 of file qoi_enc_n64.h.

◆ qoi_enc_luma()

void qoi_enc_luma	(	qoi_enc_t *	enc,
		uint8_t	green_diff,
		uint8_t	dr_dg,
		uint8_t	db_dg )

inlinestatic

Place the luma values into the QOI opcode.

Parameters

enc	QOI encoder

Definition at line 413 of file qoi_enc_n64.h.

◆ qoi_enc_reset_buffer()

bool qoi_enc_reset_buffer ( qoi_enc_t * enc )

Resets the buffer of the QOI encoder to the default state.

Parameters

enc	QOI encoder

Returns: If the buffer was reset successfully

Definition at line 651 of file qoi_enc_n64.h.

◆ qoi_enc_rgb()

void qoi_enc_rgb	(	qoi_enc_t *	enc,
		qoi_pixel_t	px )

inlinestatic

Place the RGB information into the QOI file.

Parameters

enc	QOI encoder
px	The pixel containing the RGB information to place into the QOI opcode

Definition at line 366 of file qoi_enc_n64.h.

◆ qoi_enc_rgba()

void qoi_enc_rgba	(	qoi_enc_t *	enc,
		qoi_pixel_t	px )

inlinestatic

Place the RGBA information into the QOI file.

Parameters

enc	QOI encoder
px	The pixel containing the RGBA information to place into the QOI opcode

Definition at line 378 of file qoi_enc_n64.h.

◆ qoi_enc_run()

void qoi_enc_run ( qoi_enc_t * enc )

inlinestatic

Place the run length of a pixel color information into the QOI opcode.

Parameters

enc	QOI encoder

Definition at line 423 of file qoi_enc_n64.h.

◆ qoi_enc_set_buffer()

bool qoi_enc_set_buffer	(	qoi_enc_t *	enc,
		void *	newBuffer,
		uint32_t	len,
		bool	shouldFreePrevBuffer )

Sets a buffer for the QOI encoder, automatically free if free buffer flag is set.

Parameters

enc	QOI encoder
newBuffer	the new buffer the encoder should be assigned to
len	Length of the buffer to allocate
shouldFreePrevBuffer	if true, free previous buffer

Returns: If the buffer was allocated successfully

Definition at line 568 of file qoi_enc_n64.h.

◆ qoi_encode_chunk()

void qoi_encode_chunk	(	qoi_desc_t *	desc,
		qoi_enc_t *	enc,
		void *	qoi_pixel_bytes )

Encode pixel data into QOI opcodes.

Parameters

enc	QOI encoder

Definition at line 434 of file qoi_enc_n64.h.

◆ qoi_get_be32()

uint32_t qoi_get_be32 ( uint32_t value )

inlinestatic

Extract a 32-bit big endian integer regardless of endianness.

Parameters

value The value to extract the big endian integer from

Returns: The value in big endian format

Definition at line 211 of file qoi_enc_n64.h.

◆ qoi_get_index_position()

int32_t qoi_get_index_position ( qoi_pixel_t pixel )

inlinestatic

Hashing function for pixels: up to 64 possible hash values.

Parameters

pixel The pixel to get the index position for

Returns: The index position of the pixel in the buffer

Definition at line 293 of file qoi_enc_n64.h.

◆ qoi_initalize_pixel()

void qoi_initalize_pixel ( qoi_pixel_t * pixel )

Initalizes the pixels to the default state.

Parameters

pixel The pixel to initialize

Definition at line 284 of file qoi_enc_n64.h.

◆ qoi_set_channels()

void qoi_set_channels	(	qoi_desc_t *	desc,
		uint8_t	channels )

inline

Sets the amount of channels of an image for QOI descriptor.

Parameters

desc	QOI descriptor to set the channels for
channels	The amount of channels to set for the image in the QOI descriptor

Definition at line 326 of file qoi_enc_n64.h.

◆ qoi_set_colorspace()

void qoi_set_colorspace	(	qoi_desc_t *	desc,
		uint8_t	colorspace )

inline

Sets the colorspace of an image for QOI descriptor.

Parameters

desc	QOI descriptor to set the colorspace for
colorspace	The colorspace to set for the image in the QOI descriptor

Definition at line 334 of file qoi_enc_n64.h.

◆ qoi_set_dimensions()

void qoi_set_dimensions	(	qoi_desc_t *	desc,
		uint32_t	width,
		uint32_t	height )

inline

Sets the image dimensions of an image for QOI descriptor.

Parameters

desc	QOI descriptor to set the dimensions for
width	The width to set for the image in the QOI descriptor
height	The height to set for the image in the QOI descriptor

Definition at line 317 of file qoi_enc_n64.h.

◆ qoi_set_pixel_rgb()

void qoi_set_pixel_rgb	(	qoi_pixel_t *	pixel,
		uint8_t	red,
		uint8_t	green,
		uint8_t	blue )

inline

Sets the RGB pixel by a certain pixel value.

Parameters

pixel	The pixel to set the RGB values for
red	The red value to set for the pixel
green	The green value to set for the pixel
blue	The blue value to set for the pixel

Definition at line 261 of file qoi_enc_n64.h.

◆ qoi_set_pixel_rgba()

void qoi_set_pixel_rgba	(	qoi_pixel_t *	pixel,
		uint8_t	red,
		uint8_t	green,
		uint8_t	blue,
		uint8_t	alpha )

inline

Sets the RGBA pixel by a certain pixel value including an transparency alpha value.

Parameters

pixel	The pixel to set the RGBA values for
red	The red value to set for the pixel
green	The green value to set for the pixel
blue	The blue value to set for the pixel
alpha	The alpha value to set for the pixel

Definition at line 274 of file qoi_enc_n64.h.

◆ qoi_to_be32()

uint32_t qoi_to_be32 ( uint32_t value )

inlinestatic

Write a 32-bit big endian integer regardless of endianness.

Parameters

value The value to convert to big endian format

Returns: The value in big endian format

Definition at line 227 of file qoi_enc_n64.h.

◆ read_qoi_header()

bool read_qoi_header	(	qoi_desc_t *	desc,
		void *	data )

◆ write_qoi_header()

void write_qoi_header	(	qoi_desc_t *	desc,
		void *	dest )

Writes the QOI metadata information to the file.

Parameters

desc	QOI descriptor containing the metadata information to write to the file
dest	The destination to write the metadata information to

Definition at line 342 of file qoi_enc_n64.h.

Variable Documentation

◆ QOI_MAGIC

const uint8_t QOI_MAGIC[4] = {'q', 'o', 'i', 'f'}

static

QOI magic number.

Definition at line 88 of file qoi_enc_n64.h.

◆ QOI_PADDING

const uint8_t QOI_PADDING[8] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01}

static

QOI end of file padding bytes.

Definition at line 91 of file qoi_enc_n64.h.

Data Structures

Macros

Enumerations

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ QOI_ALLOW_MEM_ALLOC

◆ QOI_ALLOW_MEM_FREE

◆ QOI_OP_DIFF

◆ QOI_OP_INDEX

◆ QOI_OP_LUMA

◆ QOI_OP_RGB

◆ QOI_OP_RGBA

◆ QOI_OP_RUN

◆ QOI_TAG

◆ QOI_TAG_MASK

Enumeration Type Documentation

◆ qoi_channels

◆ qoi_colorspace

◆ qoi_pixel_color

Function Documentation

◆ qoi_cmp_pixel()

◆ qoi_desc_init()

◆ qoi_enc_alloc_buffer()

◆ qoi_enc_diff()

◆ qoi_enc_free_buffer()

◆ qoi_enc_index()

◆ qoi_enc_init()

◆ qoi_enc_luma()

◆ qoi_enc_reset_buffer()

◆ qoi_enc_rgb()

◆ qoi_enc_rgba()

◆ qoi_enc_run()

◆ qoi_enc_set_buffer()

◆ qoi_encode_chunk()

◆ qoi_get_be32()

◆ qoi_get_index_position()

◆ qoi_initalize_pixel()

◆ qoi_set_channels()

◆ qoi_set_colorspace()

◆ qoi_set_dimensions()

◆ qoi_set_pixel_rgb()

◆ qoi_set_pixel_rgba()

◆ qoi_to_be32()

◆ read_qoi_header()

◆ write_qoi_header()

Variable Documentation

◆ QOI_MAGIC

◆ QOI_PADDING