examples/avif_example_decode_streaming.c - libavif - Git at Google

 // Copyright 2020 Joe Drago. All rights reserved.
 // SPDX-License-Identifier: BSD-2-Clause

 #include "avif/avif.h"

 #include <inttypes.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>

 // This example intends to show how a custom avifIO implementation can be used to decode
 // partially-downloaded AVIFs. Read either the avif_example_decode_file or
 // avif_example_decode_memory examples for something more basic.
 //
 // This test will emit something like this:
 //
 //     File: [file.avif @ 4823 / 125867 bytes, Metadata] parse returned: OK
 //     File: [file.avif @ 125867 / 125867 bytes, Metadata] nextImage returned: OK
 //     File: [file.avif @ 390 / 125867 bytes, IgnoreMetadata] parse returned: OK
 //     File: [file.avif @ 125867 / 125867 bytes, IgnoreMetadata] nextImage returned: OK
 //
 // In the above output, file.avif is 125867 bytes. If parsing Exif/XMP metadata is enabled,
 // avifDecoderParse() finally returns AVIF_RESULT_OK once 4823 bytes are "downloaded".
 // and requires the entire file to decode the first image (this example is a single image AVIF).
 // If Exif/XMP metadata is ignored, avifDecoderParse() only needs the first 390 bytes to return OK.
 //
 // How much of an AVIF is required to be downloaded in order to return OK from avifDecoderParse()
 // or avifDecoderNextImage() varies wildly due to the packing of the file. Ideally, the end of the
 // AVIF is simply a large mdat or moov box full of AV1 payloads, and all metadata (meta boxes,
 // Exif/XMP payloads, etc) are as close to the front as possible. Any trailing MP4 boxes (free, etc)
 // will cause avifDecoderParse() to have to wait to download those, as it can't ensure a succesful
 // parse without knowing what boxes are remaining.

 typedef struct avifIOStreamingReader
 {
     avifIO io;              // This must be first if you plan to cast this struct to an (avifIO *).
     avifROData rodata;      // The actual data.
     size_t downloadedBytes; // How many bytes have been "downloaded" so far. This is what will
                             // dictate when we return AVIF_RESULT_WAITING_ON_IO in this example.
                             // The example will slowly increment this value (from 0) until
                             // avifDecoderParse() returns something other than AVIF_RESULT_WAITING_ON_IO,
                             // and then it will continue to incremement it until avifDecoderNextImage()
                             // returns something other than AVIF_RESULT_WAITING_ON_IO.
 } avifIOStreamingReader;

 // This example has interleaved the documentation above avifIOReadFunc in avif/avif.h to help
 // explain why these checks are here.
 static avifResult avifIOStreamingReaderRead(struct avifIO * io, uint32_t readFlags, uint64_t offset, size_t size, avifROData * out)
 {
     avifIOStreamingReader * reader = (avifIOStreamingReader *)io;

     if (readFlags != 0) {
         // Unsupported readFlags
         return AVIF_RESULT_IO_ERROR;
     }

     // * If offset exceeds the size of the content (past EOF), return AVIF_RESULT_IO_ERROR.
     if (offset > reader->rodata.size) {
         return AVIF_RESULT_IO_ERROR;
     }

     // * If offset is *exactly* at EOF, provide any 0-byte buffer and return AVIF_RESULT_OK.
     if (offset == reader->rodata.size) {
         out->data = reader->rodata.data;
         out->size = 0;
         return AVIF_RESULT_OK;
     }

     // * If (offset+size) exceeds the contents' size, it must provide a truncated buffer that provides
     //   all bytes from the offset to EOF, and return AVIF_RESULT_OK.
     uint64_t availableSize = reader->rodata.size - offset;
     if (size > availableSize) {
         size = (size_t)availableSize;
     }

     // * If (offset+size) does not exceed the contents' size but the *entire range* is unavailable yet
     //   (due to network conditions or any other reason), return AVIF_RESULT_WAITING_ON_IO.
     if (offset > reader->downloadedBytes) {
         return AVIF_RESULT_WAITING_ON_IO;
     }
     if (size > (reader->downloadedBytes - offset)) {
         return AVIF_RESULT_WAITING_ON_IO;
     }

     // * If (offset+size) does not exceed the contents' size, it must provide the *entire range* and
     //   return AVIF_RESULT_OK.
     out->data = reader->rodata.data + offset;
     out->size = size;
     return AVIF_RESULT_OK;
 }

 static void avifIOStreamingReaderDestroy(struct avifIO * io)
 {
     avifFree(io);
 }

 // Returns null in case of memory allocation failure.
 static avifIOStreamingReader * avifIOCreateStreamingReader(const uint8_t * data, size_t size)
 {
     avifIOStreamingReader * reader = avifAlloc(sizeof(avifIOStreamingReader));
     if (!reader)
         return NULL;
     memset(reader, 0, sizeof(avifIOStreamingReader));

     // It is legal for io.destroy to be NULL, in which you are responsible for cleaning up
     // your own reader. This allows for a pre-existing, on-the-stack, or member variable to be
     // used as an avifIO*.
     reader->io.destroy = avifIOStreamingReaderDestroy;

     // The heart of the reader is this function. See the implementation and comments above.
     reader->io.read = avifIOStreamingReaderRead;

     // See the documentation for sizeHint in avif/avif.h. It is not required to be set, but it is recommended.
     reader->io.sizeHint = size;

     // See the documentation for persistent in avif/avif.h. Enabling this adds heavy restrictions to
     // the lifetime of the buffers you return from io.read, but cuts down on memory overhead and memcpys.
     reader->io.persistent = AVIF_TRUE;

     reader->rodata.data = data;
     reader->rodata.size = size;
     return reader;
 }

 int main(int argc, char * argv[])
 {
     if (argc != 2) {
         fprintf(stderr, "avif_example_decode_streaming [filename.avif]\n");
         return 1;
     }
     const char * inputFilename = argv[1];

     int returnCode = 1;
     avifDecoder * decoder = NULL;

     // Read entire file into fileBuffer
     FILE * f = NULL;
     uint8_t * fileBuffer = NULL;
     f = fopen(inputFilename, "rb");
     if (!f) {
         fprintf(stderr, "Cannot open file for read: %s\n", inputFilename);
         goto cleanup;
     }
     fseek(f, 0, SEEK_END);
     long fileSize = ftell(f);
     if (fileSize < 0) {
         fprintf(stderr, "Truncated file: %s\n", inputFilename);
         goto cleanup;
     }
     fseek(f, 0, SEEK_SET);
     fileBuffer = malloc(fileSize);
     long bytesRead = (long)fread(fileBuffer, 1, fileSize, f);
     if (bytesRead != fileSize) {
         fprintf(stderr, "Cannot read file: %s\n", inputFilename);
         goto cleanup;
     }

     decoder = avifDecoderCreate();
     if (!decoder) {
         fprintf(stderr, "Memory allocation failure\n");
         goto cleanup;
     }
     // Override decoder defaults here (codecChoice, requestedSource, ignoreExif, ignoreXMP, etc)

     avifIOStreamingReader * io = avifIOCreateStreamingReader(fileBuffer, fileSize);
     if (!io) {
         fprintf(stderr, "Memory allocation failure\n");
         goto cleanup;
     }
     avifDecoderSetIO(decoder, (avifIO *)io);

     for (int pass = 0; pass < 2; ++pass) {
         // This shows the difference in how much data avifDecoderParse() needs from the file
         // depending on whether or not Exif/XMP metadata is necessary. If the caller plans to
         // interpret this metadata, avifDecoderParse() will continue to return
         // AVIF_RESULT_WAITING_ON_IO until it has those payloads in their entirety (if they exist).
         decoder->ignoreExif = decoder->ignoreXMP = (pass > 0);

         // Slowly pretend to have streamed-in / downloaded more and more bytes by incrementing io->downloadedBytes
         avifResult parseResult = AVIF_RESULT_UNKNOWN_ERROR;
         for (io->downloadedBytes = 0; io->downloadedBytes <= io->io.sizeHint; ++io->downloadedBytes) {
             parseResult = avifDecoderParse(decoder);
             if (parseResult == AVIF_RESULT_WAITING_ON_IO) {
                 continue;
             }
             if (parseResult != AVIF_RESULT_OK) {
                 returnCode = 1;
             }

             // See other examples on how to access the parsed information.

             printf("File: [%s @ %zu / %" PRIu64 " bytes, %s] parse returned: %s\n",
                    inputFilename,
                    io->downloadedBytes,
                    io->io.sizeHint,
                    decoder->ignoreExif ? "IgnoreMetadata" : "Metadata",
                    avifResultToString(parseResult));
             break;
         }

         if (parseResult == AVIF_RESULT_OK) {
             for (; io->downloadedBytes <= io->io.sizeHint; ++io->downloadedBytes) {
                 avifResult nextImageResult = avifDecoderNextImage(decoder);
                 if (nextImageResult == AVIF_RESULT_WAITING_ON_IO) {
                     continue;
                 }
                 if (nextImageResult != AVIF_RESULT_OK) {
                     returnCode = 1;
                 }

                 // See other examples on how to access the pixel content of the images.

                 printf("File: [%s @ %zu / %" PRIu64 " bytes, %s] nextImage returned: %s\n",
                        inputFilename,
                        io->downloadedBytes,
                        io->io.sizeHint,
                        decoder->ignoreExif ? "IgnoreMetadata" : "Metadata",
                        avifResultToString(nextImageResult));
                 break;
             }
         }
     }

     returnCode = 0;
 cleanup:
     if (decoder) {
         avifDecoderDestroy(decoder); // this calls avifIOStreamingReaderDestroy for us
     }
     if (f) {
         fclose(f);
     }
     free(fileBuffer);
     return returnCode;
 }
	// Copyright 2020 Joe Drago. All rights reserved.
	// SPDX-License-Identifier: BSD-2-Clause

	#include "avif/avif.h"

	#include <inttypes.h>
	#include <stdio.h>
	#include <stdlib.h>
	#include <string.h>

	// This example intends to show how a custom avifIO implementation can be used to decode
	// partially-downloaded AVIFs. Read either the avif_example_decode_file or
	// avif_example_decode_memory examples for something more basic.
	//
	// This test will emit something like this:
	//
	// File: [file.avif @ 4823 / 125867 bytes, Metadata] parse returned: OK
	// File: [file.avif @ 125867 / 125867 bytes, Metadata] nextImage returned: OK
	// File: [file.avif @ 390 / 125867 bytes, IgnoreMetadata] parse returned: OK
	// File: [file.avif @ 125867 / 125867 bytes, IgnoreMetadata] nextImage returned: OK
	//
	// In the above output, file.avif is 125867 bytes. If parsing Exif/XMP metadata is enabled,
	// avifDecoderParse() finally returns AVIF_RESULT_OK once 4823 bytes are "downloaded".
	// and requires the entire file to decode the first image (this example is a single image AVIF).
	// If Exif/XMP metadata is ignored, avifDecoderParse() only needs the first 390 bytes to return OK.
	//
	// How much of an AVIF is required to be downloaded in order to return OK from avifDecoderParse()
	// or avifDecoderNextImage() varies wildly due to the packing of the file. Ideally, the end of the
	// AVIF is simply a large mdat or moov box full of AV1 payloads, and all metadata (meta boxes,
	// Exif/XMP payloads, etc) are as close to the front as possible. Any trailing MP4 boxes (free, etc)
	// will cause avifDecoderParse() to have to wait to download those, as it can't ensure a succesful
	// parse without knowing what boxes are remaining.

	typedef struct avifIOStreamingReader
	{
	avifIO io; // This must be first if you plan to cast this struct to an (avifIO *).
	avifROData rodata; // The actual data.
	size_t downloadedBytes; // How many bytes have been "downloaded" so far. This is what will
	// dictate when we return AVIF_RESULT_WAITING_ON_IO in this example.
	// The example will slowly increment this value (from 0) until
	// avifDecoderParse() returns something other than AVIF_RESULT_WAITING_ON_IO,
	// and then it will continue to incremement it until avifDecoderNextImage()
	// returns something other than AVIF_RESULT_WAITING_ON_IO.
	} avifIOStreamingReader;

	// This example has interleaved the documentation above avifIOReadFunc in avif/avif.h to help
	// explain why these checks are here.
	static avifResult avifIOStreamingReaderRead(struct avifIO * io, uint32_t readFlags, uint64_t offset, size_t size, avifROData * out)
	{
	avifIOStreamingReader * reader = (avifIOStreamingReader *)io;

	if (readFlags != 0) {
	// Unsupported readFlags
	return AVIF_RESULT_IO_ERROR;
	}

	// * If offset exceeds the size of the content (past EOF), return AVIF_RESULT_IO_ERROR.
	if (offset > reader->rodata.size) {
	return AVIF_RESULT_IO_ERROR;
	}

	// * If offset is exactly at EOF, provide any 0-byte buffer and return AVIF_RESULT_OK.
	if (offset == reader->rodata.size) {
	out->data = reader->rodata.data;
	out->size = 0;
	return AVIF_RESULT_OK;
	}

	// * If (offset+size) exceeds the contents' size, it must provide a truncated buffer that provides
	// all bytes from the offset to EOF, and return AVIF_RESULT_OK.
	uint64_t availableSize = reader->rodata.size - offset;
	if (size > availableSize) {
	size = (size_t)availableSize;
	}

	// * If (offset+size) does not exceed the contents' size but the entire range is unavailable yet
	// (due to network conditions or any other reason), return AVIF_RESULT_WAITING_ON_IO.
	if (offset > reader->downloadedBytes) {
	return AVIF_RESULT_WAITING_ON_IO;
	}
	if (size > (reader->downloadedBytes - offset)) {
	return AVIF_RESULT_WAITING_ON_IO;
	}

	// * If (offset+size) does not exceed the contents' size, it must provide the entire range and
	// return AVIF_RESULT_OK.
	out->data = reader->rodata.data + offset;
	out->size = size;
	return AVIF_RESULT_OK;
	}

	static void avifIOStreamingReaderDestroy(struct avifIO * io)
	{
	avifFree(io);
	}

	// Returns null in case of memory allocation failure.
	static avifIOStreamingReader * avifIOCreateStreamingReader(const uint8_t * data, size_t size)
	{
	avifIOStreamingReader * reader = avifAlloc(sizeof(avifIOStreamingReader));
	if (!reader)
	return NULL;
	memset(reader, 0, sizeof(avifIOStreamingReader));

	// It is legal for io.destroy to be NULL, in which you are responsible for cleaning up
	// your own reader. This allows for a pre-existing, on-the-stack, or member variable to be
	// used as an avifIO*.
	reader->io.destroy = avifIOStreamingReaderDestroy;

	// The heart of the reader is this function. See the implementation and comments above.
	reader->io.read = avifIOStreamingReaderRead;

	// See the documentation for sizeHint in avif/avif.h. It is not required to be set, but it is recommended.
	reader->io.sizeHint = size;

	// See the documentation for persistent in avif/avif.h. Enabling this adds heavy restrictions to
	// the lifetime of the buffers you return from io.read, but cuts down on memory overhead and memcpys.
	reader->io.persistent = AVIF_TRUE;

	reader->rodata.data = data;
	reader->rodata.size = size;
	return reader;
	}

	int main(int argc, char * argv[])
	{
	if (argc != 2) {
	fprintf(stderr, "avif_example_decode_streaming [filename.avif]\n");
	return 1;
	}
	const char * inputFilename = argv[1];

	int returnCode = 1;
	avifDecoder * decoder = NULL;

	// Read entire file into fileBuffer
	FILE * f = NULL;
	uint8_t * fileBuffer = NULL;
	f = fopen(inputFilename, "rb");
	if (!f) {
	fprintf(stderr, "Cannot open file for read: %s\n", inputFilename);
	goto cleanup;
	}
	fseek(f, 0, SEEK_END);
	long fileSize = ftell(f);
	if (fileSize < 0) {
	fprintf(stderr, "Truncated file: %s\n", inputFilename);
	goto cleanup;
	}
	fseek(f, 0, SEEK_SET);
	fileBuffer = malloc(fileSize);
	long bytesRead = (long)fread(fileBuffer, 1, fileSize, f);
	if (bytesRead != fileSize) {
	fprintf(stderr, "Cannot read file: %s\n", inputFilename);
	goto cleanup;
	}

	decoder = avifDecoderCreate();
	if (!decoder) {
	fprintf(stderr, "Memory allocation failure\n");
	goto cleanup;
	}
	// Override decoder defaults here (codecChoice, requestedSource, ignoreExif, ignoreXMP, etc)

	avifIOStreamingReader * io = avifIOCreateStreamingReader(fileBuffer, fileSize);
	if (!io) {
	fprintf(stderr, "Memory allocation failure\n");
	goto cleanup;
	}
	avifDecoderSetIO(decoder, (avifIO *)io);

	for (int pass = 0; pass < 2; ++pass) {
	// This shows the difference in how much data avifDecoderParse() needs from the file
	// depending on whether or not Exif/XMP metadata is necessary. If the caller plans to
	// interpret this metadata, avifDecoderParse() will continue to return
	// AVIF_RESULT_WAITING_ON_IO until it has those payloads in their entirety (if they exist).
	decoder->ignoreExif = decoder->ignoreXMP = (pass > 0);

	// Slowly pretend to have streamed-in / downloaded more and more bytes by incrementing io->downloadedBytes
	avifResult parseResult = AVIF_RESULT_UNKNOWN_ERROR;
	for (io->downloadedBytes = 0; io->downloadedBytes <= io->io.sizeHint; ++io->downloadedBytes) {
	parseResult = avifDecoderParse(decoder);
	if (parseResult == AVIF_RESULT_WAITING_ON_IO) {
	continue;
	}
	if (parseResult != AVIF_RESULT_OK) {
	returnCode = 1;
	}

	// See other examples on how to access the parsed information.

	printf("File: [%s @ %zu / %" PRIu64 " bytes, %s] parse returned: %s\n",
	inputFilename,
	io->downloadedBytes,
	io->io.sizeHint,
	decoder->ignoreExif ? "IgnoreMetadata" : "Metadata",
	avifResultToString(parseResult));
	break;
	}

	if (parseResult == AVIF_RESULT_OK) {
	for (; io->downloadedBytes <= io->io.sizeHint; ++io->downloadedBytes) {
	avifResult nextImageResult = avifDecoderNextImage(decoder);
	if (nextImageResult == AVIF_RESULT_WAITING_ON_IO) {
	continue;
	}
	if (nextImageResult != AVIF_RESULT_OK) {
	returnCode = 1;
	}

	// See other examples on how to access the pixel content of the images.

	printf("File: [%s @ %zu / %" PRIu64 " bytes, %s] nextImage returned: %s\n",
	inputFilename,
	io->downloadedBytes,
	io->io.sizeHint,
	decoder->ignoreExif ? "IgnoreMetadata" : "Metadata",
	avifResultToString(nextImageResult));
	break;
	}
	}
	}

	returnCode = 0;
	cleanup:
	if (decoder) {
	avifDecoderDestroy(decoder); // this calls avifIOStreamingReaderDestroy for us
	}
	if (f) {
	fclose(f);
	}
	free(fileBuffer);
	return returnCode;
	}