blob: da41b14f5ee192f48004f909c259f1586a15e775 [file] [log] [blame]
// 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;
}