Codec-specific options plumbing for advanced encoding settings (unused, first pass)
diff --git a/include/avif/avif.h b/include/avif/avif.h
index 3dba451..093f76f 100644
--- a/include/avif/avif.h
+++ b/include/avif/avif.h
@@ -89,7 +89,8 @@
AVIF_RESULT_NO_CODEC_AVAILABLE,
AVIF_RESULT_NO_IMAGES_REMAINING,
AVIF_RESULT_INVALID_EXIF_PAYLOAD,
- AVIF_RESULT_INVALID_IMAGE_GRID
+ AVIF_RESULT_INVALID_IMAGE_GRID,
+ AVIF_RESULT_INVALID_CODEC_SPECIFIC_OPTION
} avifResult;
const char * avifResultToString(avifResult result);
@@ -633,6 +634,7 @@
// avifEncoder
struct avifEncoderData;
+struct avifCodecSpecificOptions;
// Notes:
// * If avifEncoderWrite() returns AVIF_RESULT_OK, output must be freed with avifRWDataFree()
@@ -666,6 +668,7 @@
// Internals used by the encoder
struct avifEncoderData * data;
+ struct avifCodecSpecificOptions * csOptions;
} avifEncoder;
avifEncoder * avifEncoderCreate(void);
@@ -697,6 +700,14 @@
avifResult avifEncoderAddImage(avifEncoder * encoder, const avifImage * image, uint64_t durationInTimescales, uint32_t addImageFlags);
avifResult avifEncoderFinish(avifEncoder * encoder, avifRWData * output);
+// Codec-specific, optional "advanced" settings tuning, in form of string key/value pairs. These
+// should be set as early as possible, preferably just after creating avifEncoder but before
+// performing any other actions.
+// key must be non-NULL, but passing a NULL value will delete that key, if it exists.
+// Setting an incorrect or unknown option for the current codec will cause errors of type
+// AVIF_RESULT_INVALID_CODEC_SPECIFIC_OPTION.
+void avifEncoderSetCodecSpecificOption(avifEncoder * encoder, const char * key, const char * value);
+
// Helpers
avifBool avifImageUsesU16(const avifImage * image);
diff --git a/include/avif/internal.h b/include/avif/internal.h
index 992bc55..44af973 100644
--- a/include/avif/internal.h
+++ b/include/avif/internal.h
@@ -123,6 +123,20 @@
void avifCodecEncodeOutputDestroy(avifCodecEncodeOutput * encodeOutput);
// ---------------------------------------------------------------------------
+// avifCodecSpecificOptions (KV string pairs for advanced tuning)
+
+typedef struct avifCodecSpecificOption
+{
+ char * key; // Must be a simple lowercase alphanumeric string
+ char * value; // Free-form string to be interpreted by the codec
+} avifCodecSpecificOption;
+AVIF_ARRAY_DECLARE(avifCodecSpecificOptions, avifCodecSpecificOption, entries);
+avifCodecSpecificOptions * avifCodecSpecificOptionsCreate(void);
+void avifCodecSpecificOptionsDestroy(avifCodecSpecificOptions * csOptions);
+void avifCodecSpecificOptionsSet(avifCodecSpecificOptions * csOptions, const char * key, const char * value); // if(value==NULL), key is deleted
+avifCodecSpecificOption * avifCodecSpecificOptionsGet(avifCodecSpecificOptions * csOptions, const char * key); // Returns NULL if not found
+
+// ---------------------------------------------------------------------------
// avifCodec (abstraction layer to use different AV1 implementations)
struct avifCodec;
@@ -132,20 +146,25 @@
typedef avifBool (*avifCodecGetNextImageFunc)(struct avifCodec * codec, avifImage * image);
// EncodeImage and EncodeFinish are not required to always emit a sample, but when all images are
// encoded and EncodeFinish is called, the number of samples emitted must match the number of submitted frames.
-typedef avifBool (*avifCodecEncodeImageFunc)(struct avifCodec * codec,
- avifEncoder * encoder,
- const avifImage * image,
- avifBool alpha,
- uint32_t addImageFlags,
- avifCodecEncodeOutput * output);
+// avifCodecEncodeImageFunc may return AVIF_RESULT_UNKNOWN_ERROR to automatically emit the appropriate
+// AVIF_RESULT_ENCODE_COLOR_FAILED or AVIF_RESULT_ENCODE_ALPHA_FAILED depending on the alpha argument.
+typedef avifResult (*avifCodecEncodeImageFunc)(struct avifCodec * codec,
+ avifEncoder * encoder,
+ const avifImage * image,
+ avifBool alpha,
+ uint32_t addImageFlags,
+ avifCodecEncodeOutput * output);
typedef avifBool (*avifCodecEncodeFinishFunc)(struct avifCodec * codec, avifCodecEncodeOutput * output);
typedef void (*avifCodecDestroyInternalFunc)(struct avifCodec * codec);
typedef struct avifCodec
{
avifCodecDecodeInput * decodeInput;
- avifCodecConfigurationBox configBox; // Pre-populated by avifEncoderWrite(), available and overridable by codec impls
- struct avifCodecInternal * internal; // up to each codec to use how it wants
+ avifCodecConfigurationBox configBox; // Pre-populated by avifEncoderWrite(), available and overridable by codec impls
+ avifCodecSpecificOptions * csOptions; // Contains codec-specific KV pairs for advanced tuning.
+ // If a codec uses a value, it must mark it as used.
+ // This array is NOT owned by avifCodec.
+ struct avifCodecInternal * internal; // up to each codec to use how it wants
avifCodecOpenFunc open;
avifCodecGetNextImageFunc getNextImage;
