daala/codec.h(3)

💖 daala/codec.h — the shared libdaala C API 💖

okay bestie, sit down, hydrate, because this is the header file that is the whole shared libdaala C API. it's a section 3 manual page from the Library Functions Manual, and honestly? she's iconic. every encoder, every decoder, every little packet — they all pass through here. 🦋

---

✨ NAME ✨

daala/codec.h — The shared libdaala C API. periodt.

---

🌸 SYNOPSIS 🌸

#include 'daala_integer.h'

---

🎀 Data Structures

• struct daala_image_plane — Representation of a single component within an image or frame. one lil slice of the picture, doing her thing.
• struct daala_image — Representation of an image or video frame. the whole vibe, framed up.
• struct daala_plane_info — Subsampling factors for a plane as a power of 2. math girlie behaviour, ngl.
• struct daala_info — Configuration parameters for a codec instance. the settings screen of your dreams.
• struct daala_packet — a packet. that's it, that's the note.
• struct daala_comment — The comment information. metadata bestie.

---

💅 Macros

• #define _daala_codec_H — value (1). the include guard, guarding.
• #define OD_GNUC_PREREQ(maj, min, pat) — the compiler-prereq checker macro.
• #define OD_WARN_UNUSED_RESULT — lowkey a "bestie, pls check the return value" macro.
• #define OD_ARG_NONNULL(x) — says "this arg is not allowed to be null", fr fr.

---

🔥 Error codes

like, these are the moods this library can be in:

• #define OD_SUCCESS — value (0). No error occurred. slay. we love a zero. ✨
• #define OD_EFAULT — value (-1). An invalid pointer was provided. you handed her a bad pointer, oops.
• #define OD_EINVAL — value (-10). An invalid argument was provided. the argument was giving nothing.
• #define OD_EBADHEADER — value (-20). The contents of the header were incomplete, invalid, or unexpected.
• #define OD_ENOTFORMAT — value (-21). The header does not belong to a Daala stream. wrong fandom entirely.
• #define OD_EVERSION — value (-22). The bitstream version is too high. she's from the future, we can't handle her yet.
• #define OD_EIMPL — value (-23). The specified function is not implemented. it's giving "coming soon" but make it permanent 😭
• #define OD_EBADPACKET — value (-24). There were errors in the video data packet.

---

🌈 Colorspaces

The currently defined color space tags. pick your palette, bestie:

• #define OD_CS_UNSPECIFIED — value (0). The color space was not specified at the encoder.
• #define OD_CS_ITU_REC_470M — value (1). A Y'CbCr color space designed for NTSC content.
• #define OD_CS_ITU_REC_470BG — value (2). A Y'CbCr color space designed for PAL/SECAM content.
• #define OD_CS_ITU_REC_790 — value (3). A Y'CbCr color space designed for HD content.
• #define OD_CS_YCgCo — value (4). A Y'CgCo color space designed for sRGB content.
• #define OD_CS_NSPACES — value (5). The total number of currently defined color spaces.
• #define OD_NPLANES_MAX — value (4). The maximum number of color planes allowed in a single frame. four planes max, no more, we're not doing that.

and the type definitions, the little name-tags:

typedef struct daala_image_plane daala_image_plane
typedef struct daala_image daala_image
typedef struct daala_plane_info daala_plane_info
typedef struct daala_info daala_info
typedef struct daala_comment daala_comment

and two functions hanging out in this section:

const char * daala_version_string (void)
int daala_log_init (void)

• daala_log_init() — Initialize the logging module.

---

⭐ Bit Depths

The three video bit depths currently supported by Daala. choose your fighter:

• #define OD_BITDEPTH_MODE_8 — value (1). 8-bit mode.
• #define OD_BITDEPTH_MODE_10 — value (2). 10-bit mode.
• #define OD_BITDEPTH_MODE_12 — value (3). 12-bit mode.

and the function lineup for this part of the header:

void daala_info_init (daala_info *info)
void daala_info_clear (daala_info *info)
void daala_comment_init (daala_comment *dc)
void daala_comment_clear (daala_comment *dc)
int64_t daala_granule_basetime (void *encdec, int64_t granpos)
double daala_granule_time (void *encdec, int64_t granpos)
int daala_packet_isheader (daala_packet *dpkt)
int daala_packet_iskeyframe (daala_packet *dpkt)

• daala_info_init() — sets up a daala_info.
• daala_info_clear() — tears a daala_info back down.
• daala_comment_init() — Initializes a daala_comment section.
• daala_comment_clear() — Free resources allocated for metadata.
• daala_granule_basetime() — gives you the granule base time.
• daala_granule_time() — Converts a granule position to an absolute time in seconds.
• daala_packet_isheader() — Determines whether a Daala packet is a header or not.
• daala_packet_iskeyframe() — Determines whether a Daala packet is a key frame or not.

---

👑 Detailed Description 👑

The shared libdaala C API. that's the whole thesis, bestie. she contains multitudes.

---

🧚 Macro Definition Documentation 🧚

#define OD_GNUC_PREREQ( maj, min, pat)

Value:

(0)

#define OD_CS_UNSPECIFIED (0)

The color space was not specified at the encoder. It may be conveyed by an external means. so like… she's mysterious. we don't know her palette yet. 🙈

---

💜 Function Documentation 💜

int daala_log_init (void )

Initialize the logging module. This should be called once before invoking any other Daala functions if logging support is enabled and you want to use it. Otherwise no logging messages will be printed. so if you want the receipts, call her first. 💅

Return values

• 0 — Success. This function always succeeds. It only returns a value for convenience (e.g., for use in a static initializer).

void daala_comment_init (daala_comment * dc)

Initializes a daala_comment section. Users should free the returned data with daala_comment_clear().

Parameters

• dc — A daala_comment structure.

void daala_comment_clear (daala_comment * dc)

Free resources allocated for metadata.

Parameters

• dc — A daala_comment structure.

double daala_granule_time (void * encdec, int64_t granpos)

Converts a granule position to an absolute time in seconds. The granule position is interpreted in the context of a given daala_enc_ctx or daala_dec_ctx handle (either will suffice). either one works, she's not picky. 🫶

Parameters

• encdec — A previously allocated daala_enc_ctx or daala_dec_ctx handle.
• granpos — The granule position to convert.

Returns

The absolute time in seconds corresponding to granpos. This is the "end time" for the frame, or the latest time it should be displayed. It is not the presentation time. ok so important distinction bestie, do not mix these up.

Return values

• -1 — The given granule position was invalid (i.e. negative).

int daala_packet_isheader (daala_packet * dpkt)

Determines whether a Daala packet is a header or not. This function does no verification beyond checking the packet type bit, so it should not be used for bitstream identification. Use daala_decode_headerin() for that.

real talk: she is NOT doing a full background check here. she peeks at one bit and goes "yeah probably". for actual bitstream identification, use daala_decode_headerin(). don't come for her. 😭

Parameters

• dpkt — A daala_packet structure.

Return values

• 1 — The packet is a header packet.
• 0 — The packet is a video data packet.

int daala_packet_iskeyframe (daala_packet * dpkt)

Determines whether a Daala packet is a key frame or not. This function does no verfication beyond checking the packet type and key frame bits, so it should not be used for bitstream identification. Feed the packet to an actual decoder for that.

same energy as above: two bits checked, zero promises made. if you need the truth, feed the packet to an actual decoder. no cap.

Parameters

• dpkt — A daala_packet structure.

Return values

• 1 — The packet contains a key frame.
• 0 — The packet contains a delta frame.

---

🌟 Author 🌟

Generated automatically by Doxygen for daala from the source code. yes, a robot wrote it, and she ate. 🤖✨

---

and that's the whole page, bestie!! 🎀 source + version check: this is daala, Version unknown, dated daala/codec.h(3) — yeah the version is literally "unknown", she's mysterious like that. go forth and encode. 💖🦋🌸