From 2f4fe06f5b14efb7305b83d8b8c6f422c0ff1e8e Mon Sep 17 00:00:00 2001 From: Brad Hards Date: Thu, 28 Nov 2024 09:48:25 +1100 Subject: [PATCH] properties: add extra usage documentation --- include/avif/avif.h | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/include/avif/avif.h b/include/avif/avif.h index 03cdafe094..c3bc489ef7 100644 --- a/include/avif/avif.h +++ b/include/avif/avif.h @@ -862,8 +862,15 @@ AVIF_API avifResult avifImageAllocatePlanes(avifImage * image, avifPlanesFlags p AVIF_API void avifImageFreePlanes(avifImage * image, avifPlanesFlags planes); // Ignores already-freed planes AVIF_API void avifImageStealPlanes(avifImage * dstImage, avifImage * srcImage, avifPlanesFlags planes); -// Add arbitrary (opaque) properties to the image +// Add arbitrary (opaque) properties to the image. +// Use of these functions for known properties and boxes (e.g. ispe or meta) will likely result in +// invalid files, and should be avoided. +// If creating a ItemFullProperty, the version and flags values should be provided as the first four bytes of +// the data argument, and accounted for in the dataSize. AVIF_API avifResult avifImageAddOpaqueProperty(avifImage * image, const uint8_t boxtype[4], const uint8_t * data, size_t dataSize); +// This version adds an ItemProperty (or ItemFullProperty if version and flags are provided in data argument), using +// the user extension (uuid) mechanism, see ISO/IEC 14496-12:2022 Section 4.2. The box type is set to 'uuid' and +// does not need to be specified. AVIF_API avifResult avifImageAddUUIDProperty(avifImage * image, const uint8_t uuid[16], const uint8_t * data, size_t dataSize); // ---------------------------------------------------------------------------