"Fossies" - the Fresh Open Source Software Archive

Member "firefox-69.0.1/media/libwebp/README.mux" (17 Sep 2019, 8934 Bytes) of package /linux/www/firefox-69.0.1.source.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1           __   __  ____  ____  ____  __ __  _     __ __
    2          /  \\/  \/  _ \/  _ \/  _ \/  \  \/ \___/_ / _\
    3          \       /   __/  _  \   __/      /  /  (_/  /__
    4           \__\__/\_____/_____/__/  \__//_/\_____/__/___/v1.0.2
    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 -duration DURATION_OPTIONS [-duration ...]
   29                INPUT -o OUTPUT
   30        webpmux -strip STRIP_OPTIONS INPUT -o OUTPUT
   31        webpmux -frame FRAME_OPTIONS [-frame...] [-loop LOOP_COUNT]
   32                [-bgcolor BACKGROUND_COLOR] -o OUTPUT
   33        webpmux -info INPUT
   34        webpmux [-h|-help]
   35        webpmux -version
   36        webpmux argument_file_name
   37 
   38 GET_OPTIONS:
   39  Extract relevant data:
   40    icc       get ICC profile
   41    exif      get EXIF metadata
   42    xmp       get XMP metadata
   43    frame n   get nth frame
   44 
   45 SET_OPTIONS:
   46  Set color profile/metadata:
   47    icc  file.icc     set ICC profile
   48    exif file.exif    set EXIF metadata
   49    xmp  file.xmp     set XMP metadata
   50    where:    'file.icc' contains the ICC profile to be set,
   51              'file.exif' contains the EXIF metadata to be set
   52              'file.xmp' contains the XMP metadata to be set
   53 
   54 DURATION_OPTIONS:
   55  Set duration of selected frames:
   56    duration            set duration for each frames
   57    duration,frame      set duration of a particular frame
   58    duration,start,end  set duration of frames in the
   59                         interval [start,end])
   60    where: 'duration' is the duration in milliseconds
   61           'start' is the start frame index
   62           'end' is the inclusive end frame index
   63            The special 'end' value '0' means: last frame.
   64 
   65 STRIP_OPTIONS:
   66  Strip color profile/metadata:
   67    icc       strip ICC profile
   68    exif      strip EXIF metadata
   69    xmp       strip XMP metadata
   70 
   71 FRAME_OPTIONS(i):
   72  Create animation:
   73    file_i +di+[xi+yi[+mi[bi]]]
   74    where:    'file_i' is the i'th animation frame (WebP format),
   75              'di' is the pause duration before next frame,
   76              'xi','yi' specify the image offset for this frame,
   77              'mi' is the dispose method for this frame (0 or 1),
   78              'bi' is the blending method for this frame (+b or -b)
   79 
   80 LOOP_COUNT:
   81  Number of times to repeat the animation.
   82  Valid range is 0 to 65535 [Default: 0 (infinite)].
   83 
   84 BACKGROUND_COLOR:
   85  Background color of the canvas.
   86   A,R,G,B
   87   where:    'A', 'R', 'G' and 'B' are integers in the range 0 to 255 specifying
   88             the Alpha, Red, Green and Blue component values respectively
   89             [Default: 255,255,255,255]
   90 
   91 INPUT & OUTPUT are in WebP format.
   92 
   93 Note: The nature of EXIF, XMP and ICC data is not checked and is assumed to be
   94 valid.
   95 
   96 Note: if a single file name is passed as the argument, the arguments will be
   97 tokenized from this file. The file name must not start with the character '-'.
   98 
   99 Visualization tool:
  100 ===================
  101 
  102 The examples/ directory also contains a tool (vwebp) for viewing WebP files.
  103 It decodes the image and visualizes it using OpenGL. See the libwebp README
  104 for details on building and running this program.
  105 
  106 Mux API:
  107 ========
  108 The Mux API contains methods for adding data to and reading data from WebP
  109 files. This API currently supports XMP/EXIF metadata, ICC profile and animation.
  110 Other features may be added in subsequent releases.
  111 
  112 Example#1 (pseudo code): Creating a WebPMux object with image data, color
  113 profile and XMP metadata.
  114 
  115   int copy_data = 0;
  116   WebPMux* mux = WebPMuxNew();
  117   // ... (Prepare image data).
  118   WebPMuxSetImage(mux, &image, copy_data);
  119   // ... (Prepare ICC profile data).
  120   WebPMuxSetChunk(mux, "ICCP", &icc_profile, copy_data);
  121   // ... (Prepare XMP metadata).
  122   WebPMuxSetChunk(mux, "XMP ", &xmp, copy_data);
  123   // Get data from mux in WebP RIFF format.
  124   WebPMuxAssemble(mux, &output_data);
  125   WebPMuxDelete(mux);
  126   // ... (Consume output_data; e.g. write output_data.bytes to file).
  127   WebPDataClear(&output_data);
  128 
  129 
  130 Example#2 (pseudo code): Get image and color profile data from a WebP file.
  131 
  132   int copy_data = 0;
  133   // ... (Read data from file).
  134   WebPMux* mux = WebPMuxCreate(&data, copy_data);
  135   WebPMuxGetFrame(mux, 1, &image);
  136   // ... (Consume image; e.g. call WebPDecode() to decode the data).
  137   WebPMuxGetChunk(mux, "ICCP", &icc_profile);
  138   // ... (Consume icc_profile).
  139   WebPMuxDelete(mux);
  140   free(data);
  141 
  142 
  143 For a detailed Mux API reference, please refer to the header file
  144 (src/webp/mux.h).
  145 
  146 Demux API:
  147 ==========
  148 The Demux API enables extraction of images and extended format data from
  149 WebP files. This API currently supports reading of XMP/EXIF metadata, ICC
  150 profile and animated images. Other features may be added in subsequent
  151 releases.
  152 
  153 Code example: Demuxing WebP data to extract all the frames, ICC profile
  154 and EXIF/XMP metadata.
  155 
  156   WebPDemuxer* demux = WebPDemux(&webp_data);
  157   uint32_t width = WebPDemuxGetI(demux, WEBP_FF_CANVAS_WIDTH);
  158   uint32_t height = WebPDemuxGetI(demux, WEBP_FF_CANVAS_HEIGHT);
  159   // ... (Get information about the features present in the WebP file).
  160   uint32_t flags = WebPDemuxGetI(demux, WEBP_FF_FORMAT_FLAGS);
  161 
  162   // ... (Iterate over all frames).
  163   WebPIterator iter;
  164   if (WebPDemuxGetFrame(demux, 1, &iter)) {
  165     do {
  166       // ... (Consume 'iter'; e.g. Decode 'iter.fragment' with WebPDecode(),
  167       // ... and get other frame properties like width, height, offsets etc.
  168       // ... see 'struct WebPIterator' below for more info).
  169     } while (WebPDemuxNextFrame(&iter));
  170     WebPDemuxReleaseIterator(&iter);
  171   }
  172 
  173   // ... (Extract metadata).
  174   WebPChunkIterator chunk_iter;
  175   if (flags & ICCP_FLAG) WebPDemuxGetChunk(demux, "ICCP", 1, &chunk_iter);
  176   // ... (Consume the ICC profile in 'chunk_iter.chunk').
  177   WebPDemuxReleaseChunkIterator(&chunk_iter);
  178   if (flags & EXIF_FLAG) WebPDemuxGetChunk(demux, "EXIF", 1, &chunk_iter);
  179   // ... (Consume the EXIF metadata in 'chunk_iter.chunk').
  180   WebPDemuxReleaseChunkIterator(&chunk_iter);
  181   if (flags & XMP_FLAG) WebPDemuxGetChunk(demux, "XMP ", 1, &chunk_iter);
  182   // ... (Consume the XMP metadata in 'chunk_iter.chunk').
  183   WebPDemuxReleaseChunkIterator(&chunk_iter);
  184   WebPDemuxDelete(demux);
  185 
  186 
  187 For a detailed Demux API reference, please refer to the header file
  188 (src/webp/demux.h).
  189 
  190 AnimEncoder API:
  191 ================
  192 The AnimEncoder API can be used to create animated WebP images.
  193 
  194 Code example:
  195 
  196   WebPAnimEncoderOptions enc_options;
  197   WebPAnimEncoderOptionsInit(&enc_options);
  198   // ... (Tune 'enc_options' as needed).
  199   WebPAnimEncoder* enc = WebPAnimEncoderNew(width, height, &enc_options);
  200   while(<there are more frames>) {
  201     WebPConfig config;
  202     WebPConfigInit(&config);
  203     // ... (Tune 'config' as needed).
  204     WebPAnimEncoderAdd(enc, frame, duration, &config);
  205   }
  206   WebPAnimEncoderAssemble(enc, webp_data);
  207   WebPAnimEncoderDelete(enc);
  208   // ... (Write the 'webp_data' to a file, or re-mux it further).
  209 
  210 
  211 For a detailed AnimEncoder API reference, please refer to the header file
  212 (src/webp/mux.h).
  213 
  214 AnimDecoder API:
  215 ================
  216 This AnimDecoder API allows decoding (possibly) animated WebP images.
  217 
  218 Code Example:
  219 
  220   WebPAnimDecoderOptions dec_options;
  221   WebPAnimDecoderOptionsInit(&dec_options);
  222   // Tune 'dec_options' as needed.
  223   WebPAnimDecoder* dec = WebPAnimDecoderNew(webp_data, &dec_options);
  224   WebPAnimInfo anim_info;
  225   WebPAnimDecoderGetInfo(dec, &anim_info);
  226   for (uint32_t i = 0; i < anim_info.loop_count; ++i) {
  227     while (WebPAnimDecoderHasMoreFrames(dec)) {
  228       uint8_t* buf;
  229       int timestamp;
  230       WebPAnimDecoderGetNext(dec, &buf, &timestamp);
  231       // ... (Render 'buf' based on 'timestamp').
  232       // ... (Do NOT free 'buf', as it is owned by 'dec').
  233     }
  234     WebPAnimDecoderReset(dec);
  235   }
  236   const WebPDemuxer* demuxer = WebPAnimDecoderGetDemuxer(dec);
  237   // ... (Do something using 'demuxer'; e.g. get EXIF/XMP/ICC data).
  238   WebPAnimDecoderDelete(dec);
  239 
  240 For a detailed AnimDecoder API reference, please refer to the header file
  241 (src/webp/demux.h).
  242 
  243 
  244 Bugs:
  245 =====
  246 
  247 Please report all bugs to the issue tracker:
  248     https://bugs.chromium.org/p/webp
  249 Patches welcome! See this page to get started:
  250     http://www.webmproject.org/code/contribute/submitting-patches/
  251 
  252 Discuss:
  253 ========
  254 
  255 Email: webp-discuss@webmproject.org
  256 Web: http://groups.google.com/a/webmproject.org/group/webp-discuss