codec.h File Reference

The contract every container codec implements, and the registry that finds one. More...

#include <stddef.h>
#include <stdint.h>
#include "tinyimg/image.h"
#include "tinyimg/tinyimg.h"
#include "tinyimg/util.h"

Go to the source code of this file.

Classes
struct	TinyCodec
	One container format's implementation. More...

Typedefs
typedef int(*)	TinySniffFn(const uint8_t *buffer, size_t size)
	Tests whether a buffer looks like this codec's format.
typedef int(*)	TinyProbeFn(const uint8_t *buffer, size_t size, TinyImageInfo *info)
	Fills in what the header says, decoding no pixels.
typedef int(*)	TinyDecodeFn(TinyImage *image, const uint8_t *buffer, size_t size, const TinyDecodeOpts *opts)
	Decodes pixels, honoring the region, scale and channel count asked for.
typedef int(*)	TinyEncodeFn(const TinyImage *image, const TinyEncodeOpts *opts, TinyWriter *writer)
	Encodes an image into a byte sink.

Functions
const TinyCodec *	tiny_codec_find (TinyImageFormat format)
	Finds the codec for a format.
const TinyCodec *	tiny_codec_sniff (const uint8_t *buffer, size_t size)
	Finds the codec whose format a buffer's magic bytes match.
uint32_t	tiny_codec_count (void)
	How many codecs this build registered.
const TinyCodec *	tiny_codec_at (uint32_t index)
	The registered codec at an index, for enumerating the build's support.
int	tiny_decode_resolve (const TinyDecodeOpts *opts, uint32_t width, uint32_t height, TinyDecodeOpts *out, uint32_t *out_width, uint32_t *out_height)
	Clamps decode options against an image's real dimensions.
void	tiny_pixel_convert (uint8_t *dest, uint8_t dest_channels, const uint8_t *src, uint8_t src_channels)
	Writes one source pixel into a destination row, converting channels.

Detailed Description

The contract every container codec implements, and the registry that finds one.

Author

Gregory Mitchell (me@gm.nosp@m.itch.nosp@m.215.x.nosp@m.yz)

Version

1.0.0

Date

2026-09-01

Copyright

Copyright (c) 2026

Typedef Documentation

TinyDecodeFn

typedef int(*) TinyDecodeFn(TinyImage *image, const uint8_t *buffer, size_t size, const TinyDecodeOpts *opts)

Decodes pixels, honoring the region, scale and channel count asked for.

A decoder is free to ignore scale_den and decode at full resolution, in which case it must still return an image of the size the options imply; the planner treats scale as an optimization, not a promise.

Parameters

image	Receives the decoded image.
buffer	The bytes.
size	Number of bytes.
opts	Region, scale and channel count. Never NULL by the time a codec sees it.

Returns

int TINYIMG_OK or a negative TinyImageError.

TinyEncodeFn

typedef int(*) TinyEncodeFn(const TinyImage *image, const TinyEncodeOpts *opts, TinyWriter *writer)

Encodes an image into a byte sink.

Parameters

image	The image to encode.
opts	Quality and related settings. Never NULL by the time a codec sees it.
writer	The sink to append to.

Returns

int TINYIMG_OK or a negative TinyImageError.

TinyProbeFn

typedef int(*) TinyProbeFn(const uint8_t *buffer, size_t size, TinyImageInfo *info)

Fills in what the header says, decoding no pixels.

Parameters

buffer	The bytes.
size	Number of bytes.
info	Receives the header fields.

Returns

int TINYIMG_OK or a negative TinyImageError.

TinySniffFn

typedef int(*) TinySniffFn(const uint8_t *buffer, size_t size)

Tests whether a buffer looks like this codec's format.

Reads magic bytes only and never rejects on anything a decoder would catch, so a corrupt file of a known format still routes to the codec that can report why.

Parameters

buffer	The bytes.
size	Number of bytes.

Returns

int Non-zero when the format matches.

Function Documentation

tiny_codec_at()

const TinyCodec * tiny_codec_at

(

uint32_t

index

)

The registered codec at an index, for enumerating the build's support.

Parameters

index

Zero based index below tiny_codec_count.

Returns

const TinyCodec* The codec, or NULL when the index is out of range.

tiny_codec_count()

uint32_t tiny_codec_count

(

void

)

How many codecs this build registered.

Returns

uint32_t The count.

tiny_codec_find()

const TinyCodec * tiny_codec_find

(

TinyImageFormat

format

)

Finds the codec for a format.

Parameters

format

The format.

Returns

const TinyCodec* The codec, or NULL when this build has none.

tiny_codec_sniff()

const TinyCodec * tiny_codec_sniff	(	const uint8_t *	buffer,
		size_t	size )

Finds the codec whose format a buffer's magic bytes match.

Parameters

buffer	The bytes.
size	Number of bytes.

Returns

const TinyCodec* The codec, or NULL when nothing matched.

tiny_decode_resolve()

int tiny_decode_resolve	(	const TinyDecodeOpts *	opts,
		uint32_t	width,
		uint32_t	height,
		TinyDecodeOpts *	out,
		uint32_t *	out_width,
		uint32_t *	out_height )

Clamps decode options against an image's real dimensions.

Every codec calls this before allocating, so the region and scale rules are interpreted in one place rather than eight.

Parameters

opts	The options as the caller gave them.
width	Source width in pixels.
height	Source height in pixels.
out	Receives the clamped region, a scale denominator of 1, 2, 4 or 8, and the channel count to produce.
out_width	Receives the resulting image width.
out_height	Receives the resulting image height.

Returns

int TINYIMG_OK, TINYIMG_ERR_BOUNDS when the region starts outside the image, or TINYIMG_ERR_TOO_LARGE past TINYIMG_MAX_PIXELS.

tiny_pixel_convert()

void tiny_pixel_convert	(	uint8_t *	dest,
		uint8_t	dest_channels,
		const uint8_t *	src,
		uint8_t	src_channels )

Writes one source pixel into a destination row, converting channels.

Codecs decode into whatever channel count the file carries and hand each pixel through here, so the requested channel count costs no second pass over the image.

Parameters

dest	Destination pixel, dest_channels bytes.
dest_channels	Channels to write, 1 through 4.
src	Source pixel, src_channels bytes.
src_channels	Channels to read, 1 through 4.