Removing examples code generation and making them static.

All documentation will be provided as comments in the source files.

Change-Id: Ie609852747733c181191f864204c787a6b23ef3a

docs.mk

@@ -31,7 +31,6 @@ TXT_DOX = $(call enabled,TXT_DOX)
 
 EXAMPLE_PATH += $(SRC_PATH_BARE) #for CHANGELOG, README, etc
 
-doxyfile: $(if $(findstring examples, $(ALL_TARGETS)),examples.doxy)
 doxyfile: libs.doxy_template libs.doxy
 	@echo "    [CREATE] $@"
 	@cat $^ > $@

examples.mk

@@ -205,9 +205,9 @@ $(foreach bin,$(BINS-yes),\
 # Rules to generate the GEN_EXAMPLES sources
 .PRECIOUS: %.c
 CLEAN-OBJS += $(GEN_EXAMPLES)
-%.c: examples/%.txt
+%.c: examples/%.c
 	@echo "    [EXAMPLE] $@"
-	@$(SRC_PATH_BARE)/examples/gen_example_code.sh $< > $@
+	@cp $< $@
 
 
 # The following pairs define a mapping of locations in the distribution
@@ -252,45 +252,3 @@ INSTALL-BINS-$(CONFIG_MSVS) += $(foreach p,$(VS_PLATFORMS),\
                                $(addprefix bin/$(p)/,$(ALL_EXAMPLES:.c=.exe)))
 $(foreach proj,$(call enabled,PROJECTS),\
     $(eval $(call vcproj_template,$(proj))))
-
-
-
-#
-# Documentation Rules
-#
-%.dox: examples/%.txt
-	@echo "    [DOXY] $@"
-	@$(SRC_PATH_BARE)/examples/gen_example_text.sh $< | \
-         $(SRC_PATH_BARE)/examples/gen_example_doxy.php \
-             example_$(@:.dox=)  $(@:.dox=.c) > $@
-
-%.dox: %.c
-	@echo "    [DOXY] $@"
-	@echo "/*!\page example_$(@:.dox=) $(@:.dox=)" > $@
-	@echo "   \includelineno $(notdir $<)" >> $@
-	@echo "*/" >> $@
-
-samples.dox: examples.mk
-	@echo "    [DOXY] $@"
-	@echo "/*!\page samples Sample Code" > $@
-	@echo "    This SDK includes a number of sample applications."\
-	      "each sample documents a feature of the SDK in both prose"\
-	      "and the associated C code. In general, later samples"\
-	      "build upon prior samples, so it is best to work through the"\
-	      "list in order. The following samples are included: ">>$@
-	@$(foreach ex,$(GEN_EXAMPLES:.c=),\
-	   echo "     - \subpage example_$(ex) $($(ex).DESCRIPTION)" >> $@;)
-	@echo >> $@
-	@echo "    In addition, the SDK contains a number of utilities."\
-              "Since these utilities are built upon the concepts described"\
-              "in the sample code listed above, they are not documented in"\
-              "pieces like the samples are. Thir sourcre is included here"\
-              "for reference. The following utilities are included:" >> $@
-	@$(foreach ex,$(UTILS:.c=),\
-	   echo "     - \subpage example_$(ex) $($(ex).DESCRIPTION)" >> $@;)
-	@echo "*/" >> $@
-
-CLEAN-OBJS += examples.doxy samples.dox $(ALL_EXAMPLES:.c=.dox)
-DOCS-yes += examples.doxy samples.dox $(ALL_EXAMPLES:.c=.dox)
-examples.doxy: samples.dox $(ALL_EXAMPLES:.c=.dox)
-	@echo "INPUT += $^" > $@

examples/decode_to_md5.c

+/*
+ *  Copyright (c) 2010 The WebM project authors. All Rights Reserved.
+ *
+ *  Use of this source code is governed by a BSD-style license
+ *  that can be found in the LICENSE file in the root of the source
+ *  tree. An additional intellectual property rights grant can be found
+ *  in the file PATENTS.  All contributing project authors may
+ *  be found in the AUTHORS file in the root of the source tree.
+ */
+
+// Frame-by-frame MD5 Checksum
+// ===========================
+//
+// This example builds upon the simple decoder loop to show how checksums
+// of the decoded output can be generated. These are used for validating
+// decoder implementations against the reference implementation, for example.
+//
+// MD5 algorithm
+// -------------
+// The Message-Digest 5 (MD5) is a well known hash function. We have provided
+// an implementation derived from the RSA Data Security, Inc. MD5 Message-Digest
+// Algorithm for your use. Our implmentation only changes the interface of this
+// reference code. You must include the `md5_utils.h` header for access to these
+// functions.
+//
+// Processing The Decoded Data
+// ---------------------------
+// Each row of the image is passed to the MD5 accumulator. First the Y plane
+// is processed, then U, then V. It is important to honor the image's `stride`
+// values.
+
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#define VPX_CODEC_DISABLE_COMPAT 1
+#include "./vpx_config.h"
+#include "vpx/vp8dx.h"
+#include "vpx/vpx_decoder.h"
+#define interface (vpx_codec_vp8_dx())
+#include "md5_utils.h"
+
+#define IVF_FILE_HDR_SZ  (32)
+#define IVF_FRAME_HDR_SZ (12)
+
+static unsigned int mem_get_le32(const unsigned char *mem) {
+  return (mem[3] << 24) | (mem[2] << 16) | (mem[1] << 8) | (mem[0]);
+}
+
+static void die(const char *fmt, ...) {
+  va_list ap;
+
+  va_start(ap, fmt);
+  vprintf(fmt, ap);
+  if(fmt[strlen(fmt)-1] != '\n')
+    printf("\n");
+  exit(EXIT_FAILURE);
+}
+
+static void die_codec(vpx_codec_ctx_t *ctx, const char *s) {
+  const char *detail = vpx_codec_error_detail(ctx);
+
+  printf("%s: %s\n", s, vpx_codec_error(ctx));
+  if(detail)
+    printf("    %s\n",detail);
+  exit(EXIT_FAILURE);
+}
+
+
+int main(int argc, char **argv) {
+  FILE            *infile, *outfile;
+  vpx_codec_ctx_t  codec;
+  int              flags = 0, frame_cnt = 0;
+  unsigned char    file_hdr[IVF_FILE_HDR_SZ];
+  unsigned char    frame_hdr[IVF_FRAME_HDR_SZ];
+  unsigned char    frame[256*1024];
+  vpx_codec_err_t  res;
+
+  (void)res;
+  /* Open files */
+  if(argc!=3)
+    die("Usage: %s <infile> <outfile>\n", argv[0]);
+  if(!(infile = fopen(argv[1], "rb")))
+    die("Failed to open %s for reading", argv[1]);
+  if(!(outfile = fopen(argv[2], "wb")))
+    die("Failed to open %s for writing", argv[2]);
+
+  /* Read file header */
+  if(!(fread(file_hdr, 1, IVF_FILE_HDR_SZ, infile) == IVF_FILE_HDR_SZ
+       && file_hdr[0]=='D' && file_hdr[1]=='K' && file_hdr[2]=='I'
+       && file_hdr[3]=='F'))
+    die("%s is not an IVF file.", argv[1]);
+
+  printf("Using %s\n",vpx_codec_iface_name(interface));
+  /* Initialize codec */
+  if(vpx_codec_dec_init(&codec, interface, NULL, flags))
+    die_codec(&codec, "Failed to initialize decoder");
+
+  /* Read each frame */
+  while(fread(frame_hdr, 1, IVF_FRAME_HDR_SZ, infile) == IVF_FRAME_HDR_SZ) {
+    int               frame_sz = mem_get_le32(frame_hdr);
+    vpx_codec_iter_t  iter = NULL;
+    vpx_image_t      *img;
+
+    frame_cnt++;
+    if(frame_sz > sizeof(frame))
+      die("Frame %d data too big for example code buffer", frame_sz);
+    if(fread(frame, 1, frame_sz, infile) != frame_sz)
+      die("Frame %d failed to read complete frame", frame_cnt);
+
+    /* Decode the frame */
+    if(vpx_codec_decode(&codec, frame, frame_sz, NULL, 0))
+      die_codec(&codec, "Failed to decode frame");
+
+    /* Write decoded data to disk */
+    while((img = vpx_codec_get_frame(&codec, &iter))) {
+      unsigned int plane, y;
+
+      unsigned char  md5_sum[16];
+      MD5Context     md5;
+      int            i;
+
+      MD5Init(&md5);
+
+      for(plane=0; plane < 3; plane++) {
+        unsigned char *buf =img->planes[plane];
+
+        for (y=0; y < (plane ? (img->d_h + 1) >> 1 : img->d_h); y++) {
+          MD5Update(&md5, buf, (plane ? (img->d_w + 1) >> 1 : img->d_w));
+          buf += img->stride[plane];
+        }
+      }
+
+      MD5Final(md5_sum, &md5);
+      for (i = 0; i < 16; i++)
+        fprintf(outfile, "%02x",md5_sum[i]);
+      fprintf(outfile, "  img-%dx%d-%04d.i420\n", img->d_w, img->d_h,
+              frame_cnt);
+    }
+  }
+
+  printf("Processed %d frames.\n",frame_cnt);
+  if(vpx_codec_destroy(&codec))
+    die_codec(&codec, "Failed to destroy codec");
+
+  fclose(outfile);
+  fclose(infile);
+  return EXIT_SUCCESS;
+}

examples/decode_to_md5.txt

-@TEMPLATE decoder_tmpl.c
-Frame-by-frame MD5 Checksum
-===========================
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION
-This example builds upon the simple decoder loop to show how checksums
-of the decoded output can be generated. These are used for validating
-decoder implementations against the reference implementation, for example.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION
-
-MD5 algorithm
--------------
-The Message-Digest 5 (MD5) is a well known hash function. We have provided
-an implementation derived from the RSA Data Security, Inc. MD5 Message-Digest
-Algorithm for your use. Our implmentation only changes the interface of this
-reference code. You must include the `md5_utils.h` header for access to these
-functions.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ EXTRA_INCLUDES
-#include "md5_utils.h"
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ EXTRA_INCLUDES
-
-
-Processing The Decoded Data
----------------------------
-Each row of the image is passed to the MD5 accumulator. First the Y plane
-is processed, then U, then V. It is important to honor the image's `stride`
-values.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_DX
-unsigned char  md5_sum[16];
-MD5Context     md5;
-int            i;
-
-MD5Init(&md5);
-
-for(plane=0; plane < 3; plane++) {
-    unsigned char *buf =img->planes[plane];
-
-    for(y=0; y < (plane ? (img->d_h + 1) >> 1 : img->d_h); y++) {
-        MD5Update(&md5, buf, (plane ? (img->d_w + 1) >> 1 : img->d_w));
-        buf += img->stride[plane];
-    }
-}
-
-MD5Final(md5_sum, &md5);
-for(i=0; i<16; i++)
-    fprintf(outfile, "%02x",md5_sum[i]);
-fprintf(outfile, "  img-%dx%d-%04d.i420\n", img->d_w, img->d_h,
-        frame_cnt);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_DX

examples/decoder_tmpl.c → examples/decode_with_drops.c

@@ -8,10 +8,50 @@
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
+// Decode With Drops Example
+// =========================
+//
+// This is an example utility which drops a series of frames, as specified
+// on the command line. This is useful for observing the error recovery
+// features of the codec.
+//
+// Usage
+// -----
+// This example adds a single argument to the `simple_decoder` example,
+// which specifies the range or pattern of frames to drop. The parameter is
+// parsed as follows:
+//
+// Dropping A Range Of Frames
+// --------------------------
+// To drop a range of frames, specify the starting frame and the ending
+// frame to drop, separated by a dash. The following command will drop
+// frames 5 through 10 (base 1).
+//
+//  $ ./decode_with_drops in.ivf out.i420 5-10
+//
+//
+// Dropping A Pattern Of Frames
+// ----------------------------
+// To drop a pattern of frames, specify the number of frames to drop and
+// the number of frames after which to repeat the pattern, separated by
+// a forward-slash. The following command will drop 3 of 7 frames.
+// Specifically, it will decode 4 frames, then drop 3 frames, and then
+// repeat.
+//
+//  $ ./decode_with_drops in.ivf out.i420 3/7
+//
+//
+// Extra Variables
+// ---------------
+// This example maintains the pattern passed on the command line in the
+// `n`, `m`, and `is_range` variables:
+//
+//
+// Making The Drop Decision
+// ------------------------
+// The example decides whether to drop the frame based on the current
+// frame number, immediately before decoding the frame.
 
-/*
-@*INTRODUCTION
- */
 #include <stdarg.h>
 #include <stdio.h>
 #include <stdlib.h>
@@ -21,7 +61,6 @@
 #include "vpx/vp8dx.h"
 #include "vpx/vpx_decoder.h"
 #define interface (vpx_codec_vp8_dx())
-@EXTRA_INCLUDES
 
 
 #define IVF_FILE_HDR_SZ  (32)
@@ -41,9 +80,15 @@ static void die(const char *fmt, ...) {
     exit(EXIT_FAILURE);
 }
 
-@DIE_CODEC
+static void die_codec(vpx_codec_ctx_t *ctx, const char *s) {
+    const char *detail = vpx_codec_error_detail(ctx);
+
+    printf("%s: %s\n", s, vpx_codec_error(ctx));
+    if(detail)
+        printf("    %s\n",detail);
+    exit(EXIT_FAILURE);
+}
 
-@HELPERS
 
 int main(int argc, char **argv) {
     FILE            *infile, *outfile;
@@ -53,11 +98,20 @@ int main(int argc, char **argv) {
     unsigned char    frame_hdr[IVF_FRAME_HDR_SZ];
     unsigned char    frame[256*1024];
     vpx_codec_err_t  res;
-@@@@EXTRA_VARS
+    int              n, m, is_range;
 
     (void)res;
     /* Open files */
-@@@@USAGE
+    if(argc!=4)
+        die("Usage: %s <infile> <outfile> <N-M|N/M>\n", argv[0]);
+    {
+        char *nptr;
+        n = strtol(argv[3], &nptr, 0);
+        m = strtol(nptr+1, NULL, 0);
+        is_range = *nptr == '-';
+        if(!n || !m || (*nptr != '-' && *nptr != '/'))
+            die("Couldn't parse pattern %s\n", argv[3]);
+    }
     if(!(infile = fopen(argv[1], "rb")))
         die("Failed to open %s for reading", argv[1]);
     if(!(outfile = fopen(argv[2], "wb")))
@@ -70,7 +124,9 @@ int main(int argc, char **argv) {
         die("%s is not an IVF file.", argv[1]);
 
     printf("Using %s\n",vpx_codec_iface_name(interface));
-@@@@DEC_INIT
+    /* Initialize codec */
+    if(vpx_codec_dec_init(&codec, interface, NULL, flags))
+        die_codec(&codec, "Failed to initialize decoder");
 
     /* Read each frame */
     while(fread(frame_hdr, 1, IVF_FRAME_HDR_SZ, infile) == IVF_FRAME_HDR_SZ) {
@@ -85,18 +141,35 @@ int main(int argc, char **argv) {
         if(fread(frame, 1, frame_sz, infile) != frame_sz)
             die("Frame %d failed to read complete frame", frame_cnt);
 
-@@@@@@@@PRE_DECODE
-@@@@@@@@DECODE
+        if((is_range && frame_cnt >= n && frame_cnt <= m)
+           ||(!is_range && m - (frame_cnt-1)%m <= n)) {
+           putc('X', stdout);
+           continue;
+        }
+        putc('.', stdout);
+        fflush(stdout);
+        /* Decode the frame */
+        if(vpx_codec_decode(&codec, frame, frame_sz, NULL, 0))
+            die_codec(&codec, "Failed to decode frame");
 
         /* Write decoded data to disk */
-@@@@@@@@GET_FRAME
+        while((img = vpx_codec_get_frame(&codec, &iter))) {
             unsigned int plane, y;
 
-@@@@@@@@@@@@PROCESS_DX
+            for(plane=0; plane < 3; plane++) {
+                unsigned char *buf =img->planes[plane];
+            
+                for(y=0; y < (plane ? (img->d_h + 1) >> 1 : img->d_h); y++) {
+                    (void) fwrite(buf, 1, (plane ? (img->d_w + 1) >> 1 : img->d_w),
+                                  outfile);
+                    buf += img->stride[plane];
+                }
+            }
         }
     }
     printf("Processed %d frames.\n",frame_cnt);
-@@@@DESTROY
+    if(vpx_codec_destroy(&codec))
+        die_codec(&codec, "Failed to destroy codec");
 
     fclose(outfile);
     fclose(infile);

examples/decode_with_drops.txt

-@TEMPLATE decoder_tmpl.c
-Decode With Drops Example
-=========================
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION
-This is an example utility which drops a series of frames, as specified
-on the command line. This is useful for observing the error recovery
-features of the codec.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION
-
-Usage
------
-This example adds a single argument to the `simple_decoder` example,
-which specifies the range or pattern of frames to drop. The parameter is
-parsed as follows:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ USAGE
-if(argc!=4)
-    die("Usage: %s <infile> <outfile> <N-M|N/M>\n", argv[0]);
-{
-    char *nptr;
-    n = strtol(argv[3], &nptr, 0);
-    m = strtol(nptr+1, NULL, 0);
-    is_range = *nptr == '-';
-    if(!n || !m || (*nptr != '-' && *nptr != '/'))
-        die("Couldn't parse pattern %s\n", argv[3]);
-}
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ USAGE
-
-
-Dropping A Range Of Frames
---------------------------
-To drop a range of frames, specify the starting frame and the ending
-frame to drop, separated by a dash. The following command will drop
-frames 5 through 10 (base 1).
-
-  $ ./decode_with_drops in.ivf out.i420 5-10
-
-
-Dropping A Pattern Of Frames
-----------------------------
-To drop a pattern of frames, specify the number of frames to drop and
-the number of frames after which to repeat the pattern, separated by
-a forward-slash. The following command will drop 3 of 7 frames.
-Specifically, it will decode 4 frames, then drop 3 frames, and then
-repeat.
-
-  $ ./decode_with_drops in.ivf out.i420 3/7
-
-
-Extra Variables
----------------
-This example maintains the pattern passed on the command line in the
-`n`, `m`, and `is_range` variables:
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ EXTRA_VARS
-int              n, m, is_range;
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ EXTRA_VARS
-
-
-Making The Drop Decision
-------------------------
-The example decides whether to drop the frame based on the current
-frame number, immediately before decoding the frame.
-
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PRE_DECODE
-if((is_range && frame_cnt >= n && frame_cnt <= m)
-   ||(!is_range && m - (frame_cnt-1)%m <= n)) {
-   putc('X', stdout);
-   continue;
-}
-putc('.', stdout);
-fflush(stdout);
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PRE_DECODE

examples/decode_with_partial_drops.c

+/*
+ *  Copyright (c) 2010 The WebM project authors. All Rights Reserved.
+ *
+ *  Use of this source code is governed by a BSD-style license
+ *  that can be found in the LICENSE file in the root of the source
+ *  tree. An additional intellectual property rights grant can be found
+ *  in the file PATENTS.  All contributing project authors may
+ *  be found in the AUTHORS file in the root of the source tree.
+ */
+
+// Decode With Partial Drops Example
+// =========================
+//
+// This is an example utility which drops a series of frames (or parts of
+// frames), as specified on the command line. This is useful for observing the
+// error recovery features of the codec.
+//
+// Usage
+// -----
+// This example adds a single argument to the `simple_decoder` example,
+// which specifies the range or pattern of frames to drop. The parameter is
+// parsed as follows.
+//
+// Dropping A Range Of Frames
+// --------------------------
+// To drop a range of frames, specify the starting frame and the ending
+// frame to drop, separated by a dash. The following command will drop
+// frames 5 through 10 (base 1).
+//
+//  $ ./decode_with_partial_drops in.ivf out.i420 5-10
+//
+//
+// Dropping A Pattern Of Frames
+// ----------------------------
+// To drop a pattern of frames, specify the number of frames to drop and
+// the number of frames after which to repeat the pattern, separated by
+// a forward-slash. The following command will drop 3 of 7 frames.
+// Specifically, it will decode 4 frames, then drop 3 frames, and then
+// repeat.
+//
+//  $ ./decode_with_partial_drops in.ivf out.i420 3/7
+//
+// Dropping Random Parts Of Frames
+// -------------------------------
+// A third argument tuple is available to split the frame into 1500 bytes pieces
+// and randomly drop pieces rather than frames. The frame will be split at
+// partition boundaries where possible. The following example will seed the RNG
+// with the seed 123 and drop approximately 5% of the pieces. Pieces which
+// are depending on an already dropped piece will also be dropped.
+//
+//  $ ./decode_with_partial_drops in.ivf out.i420 5,123
+//
+// Extra Variables
+// ---------------
+// This example maintains the pattern passed on the command line in the
+// `n`, `m`, and `is_range` variables:
+//
+// Making The Drop Decision
+// ------------------------
+// The example decides whether to drop the frame based on the current
+// frame number, immediately before decoding the frame.
+
+#include <stdarg.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#define VPX_CODEC_DISABLE_COMPAT 1
+#include "./vpx_config.h"
+#include "vpx/vp8dx.h"
+#include "vpx/vpx_decoder.h"
+#define interface (vpx_codec_vp8_dx())
+#include <time.h>
+
+
+#define IVF_FILE_HDR_SZ  (32)
+#define IVF_FRAME_HDR_SZ (12)
+
+static unsigned int mem_get_le32(const unsigned char *mem) {
+    return (mem[3] << 24)|(mem[2] << 16)|(mem[1] << 8)|(mem[0]);
+}
+
+static void die(const char *fmt, ...) {
+    va_list ap;
+
+    va_start(ap, fmt);
+    vprintf(fmt, ap);
+    if(fmt[strlen(fmt)-1] != '\n')
+        printf("\n");
+    exit(EXIT_FAILURE);
+}
+
+static void die_codec(vpx_codec_ctx_t *ctx, const char *s) {
+    const char *detail = vpx_codec_error_detail(ctx);
+
+    printf("%s: %s\n", s, vpx_codec_error(ctx));
+    if(detail)
+        printf("    %s\n",detail);
+    exit(EXIT_FAILURE);
+}
+
+struct parsed_header