Add a new libtheora_info example program.
authorRalph Giles <giles@xiph.org>
Thu, 2 Dec 2010 19:28:11 +0000 (19:28 +0000)
committerRalph Giles <giles@xiph.org>
Thu, 2 Dec 2010 19:28:11 +0000 (19:28 +0000)
This program shows how to query a few version-dependent library
paramenters, such as the vendor string and maximum speed level,
and prints a summary to stdout in 'header: value' format.

I mostly wanted this as a utility to get the maximum speed level
for benchmark scripts, but thought it structuring it as an example
was better than stuffing it in tools.

It would be reasonable to extend this to return decoder parameters
like the maximum preprocessing level.

svn path=/trunk/theora/; revision=17709

SConstruct
examples/Makefile.am
examples/libtheora_info.c [new file with mode: 0644]

index 8dde3d6..c381fd9 100644 (file)
@@ -213,6 +213,15 @@ dump_psnr.Append(LIBS='m')
 dump_psnr_Sources = Split("""dump_psnr.c ../lib/libtheoradec.a""")
 dump_psnr.Program('examples/dump_psnr', path('examples', dump_psnr_Sources))
 
+libtheora_info = env.Clone()
+libtheora_info_Sources = Split("""
+        libtheora_info.c
+        ../lib/libtheoraenc.a
+        ../lib/libtheoradec.a
+  """)
+libtheora_info.Program('examples/libtheora_info',
+                       path('examples', libtheora_info_Sources))
+
 if have_vorbis:
   encex = dump_video.Clone()
   encex.ParseConfig('pkg-config --cflags --libs vorbisenc vorbis')
index fe66a21..fe5f670 100644 (file)
@@ -2,7 +2,8 @@
 
 INCLUDES = -I$(top_srcdir)/include 
 
-noinst_PROGRAMS = dump_video dump_psnr $(BUILDABLE_EXAMPLES)
+noinst_PROGRAMS = dump_video dump_psnr libtheora_info \
+       $(BUILDABLE_EXAMPLES)
 
 # possible contents of BUILDABLE_EXAMPLES:
 EXTRA_PROGRAMS = player_example encoder_example png2theora
@@ -20,6 +21,9 @@ dump_psnr_SOURCES = dump_psnr.c
 EXTRA_dump_psnr_SOURCES = getopt.c getopt1.c getopt.h
 dump_psnr_LDADD = $(GETOPT_OBJS) $(LDADDDEC) -lm
 
+libtheora_info_SOURCES = libtheora_info.c
+libtheora_info_LDADD = $(LDADDENC)
+
 player_example_SOURCES = player_example.c
 player_example_CFLAGS = $(SDL_CFLAGS) $(OGG_CFLAGS) $(VORBIS_CFLAGS)
 player_example_LDADD = $(LDADDDEC) $(SDL_LIBS) $(VORBIS_LIBS) $(OSS_LIBS)
diff --git a/examples/libtheora_info.c b/examples/libtheora_info.c
new file mode 100644 (file)
index 0000000..b85a16f
--- /dev/null
@@ -0,0 +1,139 @@
+/********************************************************************
+ *                                                                  *
+ * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE.   *
+ * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS     *
+ * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
+ * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING.       *
+ *                                                                  *
+ * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2010                *
+ * by the Xiph.Org Foundation and contributors http://www.xiph.org/ *
+ *                                                                  *
+ ********************************************************************
+
+  function: example of querying various library parameters.
+  last mod: $Id$
+
+ ********************************************************************/
+
+#ifdef HAVE_CONFIG_H
+# include <config.h>
+#endif
+
+#include <stdio.h>
+#include <stdlib.h>
+
+#include "theora/theoraenc.h"
+
+
+/* Print the library's bitstream version number
+   This is the highest supported bitstream version number,
+   not the version number of the implementation itself. */
+int print_version(void)
+{
+    unsigned version = th_version_number();
+
+    fprintf(stdout, "Bitstream: %d.%d.%d (0x%06X)\n",
+        (version >> 16) & 0xff, (version >> 8) & 0xff, (version) & 0xff,
+        version);
+
+    return 0;
+}
+
+/* Print the library's own version string
+   This is generally the same at the vendor string embedded
+   in encoded files. */
+int print_version_string(void)
+{
+    const char *version = th_version_string();
+
+    if (version == NULL) {
+      fprintf(stderr, "Error querying libtheora version string.\n");
+      return -1;
+    }
+
+    fprintf(stdout, "Version: %s\n", version);
+
+    return 0;
+}
+
+/* Generate a dummy encoder context for use in th_encode_ctl queries */
+th_enc_ctx *dummy_encode_ctx(void)
+{
+    th_enc_ctx *ctx;
+    th_info info;
+
+    /* set the minimal video parameters */
+    th_info_init(&info);
+    info.frame_width=320;
+    info.frame_height=240;
+
+    /* allocate and initialize a context object */
+    ctx = th_encode_alloc(&info);
+    if (ctx == NULL) {
+        fprintf(stderr, "Error allocating encoder context.\n");
+    }
+
+    /* clear the info struct */
+    th_info_clear(&info);
+
+    return ctx;
+}
+
+/* Query the current and maximum values for the 'speed level' setting.
+   This can be used to ask the encoder to trade off encoding quality
+   vs. performance cost, for example to adapt to realtime constraints. */
+int check_speed_level(th_enc_ctx *ctx, int *current, int *max)
+{
+    int ret;
+
+    /* query the current speed level */
+    ret = th_encode_ctl(ctx, TH_ENCCTL_GET_SPLEVEL, current, sizeof(int));
+    if (ret) {
+        fprintf(stderr, "Error %d getting current speed level.\n", ret);
+        return ret;
+    }
+    /* query the maximum speed level, which varies by encoder version */
+    ret = th_encode_ctl(ctx, TH_ENCCTL_GET_SPLEVEL_MAX, max, sizeof(int));
+    if (ret) {
+        fprintf(stderr, "Error %d getting max speed level.\n", ret);
+        return ret;
+    }
+
+    return 0;
+}
+
+/* Print the current and maximum speed level settings */
+int print_speed_level(th_enc_ctx *ctx)
+{
+    int current = -1;
+    int max = -1;
+    int ret;
+
+    ret = check_speed_level(ctx, &current, &max);
+    if (ret == 0) {
+        fprintf(stdout, "Default speed level: %d\n", current);
+        fprintf(stdout, "Maximum speed level: %d\n", max);
+    }
+
+    return ret;
+}
+
+int main(int argc, char **argv) {
+    th_enc_ctx *ctx;
+
+    /* print versioning */
+    print_version_string();
+    print_version();
+
+    /* allocate a generic context for queries that require it */
+    ctx = dummy_encode_ctx();
+    if (ctx != NULL) {
+        /* dump the speed level setting */
+        print_speed_level(ctx);
+        /* clean up */
+        th_encode_free(ctx);
+    }
+
+    return 0;
+}
+