Commit 50fa5859 authored by Dmitry Kovalev's avatar Dmitry Kovalev

Removing examples code generation and making them static.

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

Change-Id: Ie609852747733c181191f864204c787a6b23ef3a
parent fdad4fd2
......@@ -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 $^ > $@
......
......@@ -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 += $^" > $@
/*
* 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;
}
@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
......@@ -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);
......
@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
This diff is collapsed.
@TEMPLATE decoder_tmpl.c
Decode With Partial Drops Example
=========================
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION
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.
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ EXTRA_INCLUDES
#include <time.h>
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ EXTRA_INCLUDES
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ HELPERS
struct parsed_header
{
char key_frame;
int version;
char show_frame;
int first_part_size;
};
int next_packet(struct parsed_header* hdr, int pos, int length, int mtu)
{
int size = 0;
int remaining = length - pos;
/* Uncompressed part is 3 bytes for P frames and 10 bytes for I frames */
int uncomp_part_size = (hdr->key_frame ? 10 : 3);
/* number of bytes yet to send from header and the first partition */
int remainFirst = uncomp_part_size + hdr->first_part_size - pos;
if (remainFirst > 0)
{
if (remainFirst <= mtu)
{
size = remainFirst;
}
else
{
size = mtu;
}
return size;
}
/* second partition; just slot it up according to MTU */
if (remaining <= mtu)
{
size = remaining;
return size;
}
return mtu;
}
void throw_packets(unsigned char* frame, int* size, int loss_rate,
int* thrown, int* kept)
{
unsigned char loss_frame[256*1024];
int pkg_size = 1;
int pos = 0;
int loss_pos = 0;
struct parsed_header hdr;
unsigned int tmp;
int mtu = 1500;
if (*size < 3)
{
return;
}
putc('|', stdout);
/* parse uncompressed 3 bytes */
tmp = (frame[2] << 16) | (frame[1] << 8) | frame[0];
hdr.key_frame = !(tmp & 0x1); /* inverse logic */
hdr.version = (tmp >> 1) & 0x7;
hdr.show_frame = (tmp >> 4) & 0x1;
hdr.first_part_size = (tmp >> 5) & 0x7FFFF;
/* don't drop key frames */
if (hdr.key_frame)
{
int i;
*kept = *size/mtu + ((*size % mtu > 0) ? 1 : 0); /* approximate */
for (i=0; i < *kept; i++)
putc('.', stdout);
return;
}
while ((pkg_size = next_packet(&hdr, pos, *size, mtu)) > 0)
{
int loss_event = ((rand() + 1.0)/(RAND_MAX + 1.0) < loss_rate/100.0);
if (*thrown == 0 && !loss_event)
{
memcpy(loss_frame + loss_pos, frame + pos, pkg_size);
loss_pos += pkg_size;
(*kept)++;
putc('.', stdout);
}
else
{
(*thrown)++;
putc('X', stdout);
}
pos += pkg_size;
}
memcpy(frame, loss_frame, loss_pos);
memset(frame + loss_pos, 0, *size - loss_pos);
*size = loss_pos;
}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ HELPERS
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DEC_INIT
/* Initialize codec */
flags = VPX_CODEC_USE_ERROR_CONCEALMENT;
res = vpx_codec_dec_init(&codec, interface, &dec_cfg, flags);
if(res)
die_codec(&codec, "Failed to initialize decoder");
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DEC_INIT
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 || argc > 6)
die("Usage: %s <infile> <outfile> [-t <num threads>] <N-M|N/M|L,S>\n",