src/SDL2/external/libwebp-0.3.0/README.mux

   1           __   __  ____  ____  ____  __ __  _     __ __
   2          /  \\/  \/  _ \/  _ \/  _ \/  \  \/ \___/_ / _\
   3          \       /   __/  _  \   __/      /  /  (_/  /__
   4           \__\__/\_____/_____/__/  \__//_/\_____/__/___/v0.1.0
   5
   6
   7 Description:
   8 ============
   9
  10 WebPMux: set of two libraries 'Mux' and 'Demux' for creation, extraction and
  11 manipulation of an extended format WebP file, which can have features like
  12 color profile, metadata and animation. Reference command-line tools 'webpmux'
  13 and 'vwebp' as well as the WebP container specification
  14 'doc/webp-container-spec.txt' are also provided in this package.
  15
  16 WebP Mux tool:
  17 ==============
  18
  19 The examples/ directory contains a tool (webpmux) for manipulating WebP
  20 files. The webpmux tool can be used to create an extended format WebP file and
  21 also to extract or strip relevant data from such a file.
  22
  23 A list of options is available using the -help command line flag:
  24
  25 > webpmux -help
  26 Usage: webpmux -get GET_OPTIONS INPUT -o OUTPUT
  27        webpmux -set SET_OPTIONS INPUT -o OUTPUT
  28        webpmux -strip STRIP_OPTIONS INPUT -o OUTPUT
  29        webpmux -frame FRAME_OPTIONS [-frame...] [-loop LOOP_COUNT]
  30                [-bgcolor BACKGROUND_COLOR] -o OUTPUT
  31        webpmux -info INPUT
  32        webpmux [-h|-help]
  33        webpmux -version
  34
  35 GET_OPTIONS:
  36  Extract relevant data.
  37    icc       Get ICC profile.
  38    exif      Get EXIF metadata.
  39    xmp       Get XMP metadata.
  40    frame n   Get nth frame.
  41
  42 SET_OPTIONS:
  43  Set color profile/metadata.
  44    icc  file.icc     Set ICC profile.
  45    exif file.exif    Set EXIF metadata.
  46    xmp  file.xmp     Set XMP metadata.
  47    where:    'file.icc' contains the ICC profile to be set,
  48              'file.exif' contains the EXIF metadata to be set
  49              'file.xmp' contains the XMP metadata to be set
  50
  51 STRIP_OPTIONS:
  52  Strip color profile/metadata.
  53    icc       Strip ICC profile.
  54    exif      Strip EXIF metadata.
  55    xmp       Strip XMP metadata.
  56
  57 FRAME_OPTIONS(i):
  58  Create animation.
  59    file_i +di+xi+yi+mi
  60    where:    'file_i' is the i'th animation frame (WebP format),
  61              'di' is the pause duration before next frame.
  62              'xi','yi' specify the image offset for this frame.
  63              'mi' is the dispose method for this frame (0 or 1).
  64
  65 LOOP_COUNT:
  66  Number of times to repeat the animation.
  67  Valid range is 0 to 65535 [Default: 0 (infinite)].
  68
  69 BACKGROUND_COLOR:
  70  Background color of the canvas.
  71   A,R,G,B
  72   where:    'A', 'R', 'G' and 'B' are integers in the range 0 to 255 specifying
  73             the Alpha, Red, Green and Blue component values respectively
  74             [Default: 255,255,255,255].
  75
  76 INPUT & OUTPUT are in WebP format.
  77
  78 Note: The nature of EXIF, XMP and ICC data is not checked and is assumed to be
  79 valid.
  80
  81 Visualization tool:
  82 ===================
  83
  84 The examples/ directory also contains a tool (vwebp) for viewing WebP files.
  85 It decodes the image and visualizes it using OpenGL. See the libwebp README
  86 for details on building and running this program.
  87
  88 Mux API:
  89 ========
  90 The Mux API contains methods for adding data to and reading data from WebP
  91 files. This API currently supports XMP/EXIF metadata, ICC profile and animation.
  92 Other features may be added in subsequent releases.
  93
  94 Example#1 (pseudo code): Creating a WebPMux object with image data, color
  95 profile and XMP metadata.
  96
  97   int copy_data = 0;
  98   WebPMux* mux = WebPMuxNew();
  99   // ... (Prepare image data).
 100   WebPMuxSetImage(mux, &image, copy_data);
 101   // ... (Prepare ICC profile data).
 102   WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data);
 103   // ... (Prepare XMP metadata).
 104   WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data);
 105   // Get data from mux in WebP RIFF format.
 106   WebPMuxAssemble(mux, &output_data);
 107   WebPMuxDelete(mux);
 108   // ... (Consume output_data; e.g. write output_data.bytes to file).
 109   WebPDataClear(&output_data);
 110
 111
 112 Example#2 (pseudo code): Get image and color profile data from a WebP file.
 113
 114   int copy_data = 0;
 115   // ... (Read data from file).
 116   WebPMux* mux = WebPMuxCreate(&data, copy_data);
 117   WebPMuxGetFrame(mux, 1, &image);
 118   // ... (Consume image; e.g. call WebPDecode() to decode the data).
 119   WebPMuxGetChunk(mux, "ICCP", &icc_profile);
 120   // ... (Consume icc_profile).
 121   WebPMuxDelete(mux);
 122   free(data);
 123
 124
 125 For a detailed Mux API reference, please refer to the header file
 126 (src/webp/mux.h).
 127
 128 Demux API:
 129 ==========
 130 The Demux API enables extraction of images and extended format data from
 131 WebP files. This API currently supports reading of XMP/EXIF metadata, ICC
 132 profile and animated images. Other features may be added in subsequent
 133 releases.
 134
 135 Code Example: Demuxing WebP data to extract all the frames, ICC profile
 136 and EXIF/XMP metadata.
 137
 138   WebPDemuxer* demux = WebPDemux(&webp_data);
 139   uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH);
 140   uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT);
 141   // ... (Get information about the features present in the WebP file).
 142   uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS);
 143
 144   // ... (Iterate over all frames).
 145   WebPIterator iter;
 146   if (WebPDemuxGetFrame(demux, 1, &iter)) {
 147     do {
 148       // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(),
 149       // ... and get other frame properties like width, height, offsets etc.
 150       // ... see 'struct WebPIterator' below for more info).
 151     } while (WebPDemuxNextFrame(&iter));
 152     WebPDemuxReleaseIterator(&iter);
 153   }
 154
 155   // ... (Extract metadata).
 156   WebPChunkIterator chunk_iter;
 157   if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter);
 158   // ... (Consume the ICC profile in 'chunk_iter.chunk').
 159   WebPDemuxReleaseChunkIterator(&chunk_iter);
 160   if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter);
 161   // ... (Consume the EXIF metadata in 'chunk_iter.chunk').
 162   WebPDemuxReleaseChunkIterator(&chunk_iter);
 163   if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter);
 164   // ... (Consume the XMP metadata in 'chunk_iter.chunk').
 165   WebPDemuxReleaseChunkIterator(&chunk_iter);
 166   WebPDemuxDelete(demux);
 167
 168
 169 For a detailed Demux API reference, please refer to the header file
 170 (src/webp/demux.h).
 171
 172
 173 Bugs:
 174 =====
 175
 176 Please report all bugs to our issue tracker:
 177     http://code.google.com/p/webp/issues
 178 Patches welcome! See this page to get started:
 179     http://www.webmproject.org/code/contribute/submitting-patches/
 180
 181 Discuss:
 182 ========
 183
 184 Email: webp-discuss@webmproject.org
 185 Web: http://groups.google.com/a/webmproject.org/group/webp-discuss