[xiph-commits] r7157 - trunk/speex

[conrad at dactyl.lonelymoon.com]

Author: conrad
Date: Thu Jul 15 21:56:59 2004
New Revision: 7157

Added:
trunk/speex/README.symbian
Log:
added README.symbian, describing how to build a modified libspeex for
Symbian OS, and how to modify applications to use it.


Added: trunk/speex/README.symbian
===================================================================
--- trunk/speex/README.symbian	2004-07-16 04:53:26 UTC (rev 7156)
+++ trunk/speex/README.symbian	2004-07-16 04:56:59 UTC (rev 7157)
@@ -0,0 +1,111 @@
+Using Speex on Symbian OS
+Conrad Parker and Colin Ward, CSIRO Australia, July 2004
+
+
+Introduction
+------------
+
+Some minor modifications to libspeex and applications using the libspeex API
+are required due to the following limitation imposed on DLLs in Symbian OS:
+
+    The Symbian OS architecture does not allow DLLs to have a data
+    segment (initialised or uninitialised).
+
+    -- Coding Idioms for Symbian OS, Oct 2002 [1]
+
+This document outlines how to build libspeex for Symbian OS, and how to
+develop applications using the modified libspeex API.
+
+Note that these modifications have been implemented in a portable manner so
+that they may also be used on other platforms with similar restrictions,
+and may be safely tested on more forgiving platforms such as Unix/Linux.
+
+
+libspeex build modifications
+----------------------------
+
+The modifications required for libspeex on Symbian OS are fully contained in
+the file libspeex/modes_noglobals.c. This file should be built instead of
+libspeex/modes.c.
+
+Additionally, the header file include/speex/speex_noglobals.h should be
+installed into the system include directory, along with the other
+speex_* headers.
+
+
+Developing applications for libspeex modified for Symbian OS
+------------------------------------------------------------
+
+The only part of the libspeex API which has been modified for Symbian OS,
+and thus affects user code which links against libspeex, is the removal of
+statically defined SpeexMode structures: speex_nb_mode, speex_wb_mode,
+speex_uwb_mode, and the array speex_mode_list[]. All other aspects of
+application development using the libspeex API remain unchanged.
+
+
+  1. applications must additionally include the header:
+
++    #include <speex_noglobals.h>
+
+
+  2. any references to the statically defined SpeexMode structures must be
+     replaced by a call to a constructor for that mode; and the
+     constructed mode must later be free'd appropriately.
+
+     * References to the statically defined array speex_mode_list[modeID]
+     must be replaced by a call to speex_mode_new_byID (modeID):
+
+-      mode = speex_mode_list[modeID];
++      mode = speex_mode_new_byID (modeID);
+
+     and later free'd:
+
++      speex_mode_free_byID (mode, modeID);
+
+     note that you must remember the association between a constructed
+     mode and its modeID in order to correctly free it later. Failure to
+     do so may introduce memory leaks or runtime errors.
+
+     * References to the statically defined mode structures must be replaced:
+
+       SpeexMode * mode1, * mode2, * mode3;
+
+-      mode1 = &speex_nb_mode;
++      mode1 = speex_nb_mode_new ();
+
+-      mode2 = &speex_wb_mode;
++      mode2 = speex_wb_mode_new ();
+
+-      mode3 = &speex_uwb_mode;
++      mode3 = speex_uwb_mode_new ();
+
+     Constructed modes must be free'd after use:
+
++      speex_nb_mode_free (mode1);
++      speex_wb_mode_free (mode2);
++      speex_uwb_mode_free (mode3);
+
+
+  3. It is fairly easy to conditionally build an application for either
+     usage of the libspeex API. For example using GNU Autoconf, you can
+     check for the existence of a symbol such as speex_mode_new_byID in
+     configure.ac. The following example is from libfishsound[2]:
+
+    dnl Test for libspeex SPEEX_DISABLE_GLOBAL_POINTERS API
+    dnl If so, we need to use a different API to access available modes,
+    dnl and free them after use.
+    AC_CHECK_LIB(speex, speex_mode_new_byID, DISABLE_GLOBAL_POINTERS="yes",
+      DISABLE_GLOBAL_POINTERS="no")
+    if test "x$DISABLE_GLOBAL_POINTERS" = xyes ; then
+      AC_DEFINE(SPEEX_DISABLE_GLOBAL_POINTERS, ,
+       [Define if libspeex uses SPEEX_DISABLE_GLOBAL_POINTERS API])
+    fi
+
+
+References
+----------
+
+[1] http://www.symbian.com/developer/techlib/papers/coding_idioms/2002_10_09_codingSymbianOS.pdf
+
+[2] http://www.annodex.net/software/libfishsound/
+