2f8c28553b95001276101da7032a4ad10a3750f6
[speexdsp.git] / README.symbian
1 Using Speex on Symbian OS
2 Conrad Parker and Colin Ward, CSIRO Australia, July 2004
3
4
5 Introduction
6 ------------
7
8 Some minor modifications to libspeex and applications using the libspeex API
9 are required due to the following limitation imposed on DLLs in Symbian OS:
10
11     The Symbian OS architecture does not allow DLLs to have a data
12     segment (initialised or uninitialised). 
13
14     -- Coding Idioms for Symbian OS, Oct 2002 [1]
15
16 This file (README.symbian) outlines how to build libspeex for Symbian OS,
17 and how to develop applications using the modified libspeex API.
18
19 Note that these modifications have been implemented in a portable manner so
20 that they may also be used on other platforms with similar restrictions,
21 and may be safely tested on more forgiving platforms such as Unix/Linux.
22
23
24 libspeex build modifications
25 ----------------------------
26
27 The modifications required for libspeex on Symbian OS are fully contained in
28 the file libspeex/modes_noglobals.c. This file should be built instead of
29 libspeex/modes.c.
30
31 Additionally, the header file include/speex/speex_noglobals.h should be
32 installed into the system include directory, along with the other
33 speex_* headers.
34
35 When building in a GNU environment, this behaviour can be configured by:
36
37   ./configure --disable-global-pointers
38
39 The symbian/ directory contains the following files for Symbian's abuild tool:
40
41   bld.inf    Component definition file
42   speex.mmp  Project specification file
43   config.h   Configuration options for both emulator and device builds
44
45
46 Developing applications for libspeex modified for Symbian OS
47 ------------------------------------------------------------
48
49 The only part of the libspeex API which has been modified for Symbian OS,
50 and thus affects user code which links against libspeex, is the removal of
51 statically defined SpeexMode structures: speex_nb_mode, speex_wb_mode,
52 speex_uwb_mode, and the array speex_mode_list[]. All other aspects of
53 application development using the libspeex API remain unchanged.
54
55
56   1. applications must additionally include the header:
57
58 +    #include <speex_noglobals.h>
59
60
61   2. any references to the statically defined SpeexMode structures must be
62      replaced by a call to a constructor for that mode; and the
63      constructed mode must later be free'd appropriately.
64
65      * References to the statically defined array speex_mode_list[modeID]
66      must be replaced by a call to speex_mode_new (modeID):
67
68 -      mode = speex_mode_list[modeID];
69 +      mode = speex_mode_new (modeID);
70
71      and later free'd:
72
73 +      speex_mode_destroy (mode, modeID);
74
75      * References to the statically defined mode structures must be replaced:
76
77        SpeexMode * mode1, * mode2, * mode3;
78
79 -      mode1 = &speex_nb_mode;
80 +      mode1 = speex_mode_new (SPEEX_MODEID_NB);
81
82 -      mode2 = &speex_wb_mode;
83 +      mode2 = speex_mode_new (SPEEX_MODEID_WB);
84
85 -      mode3 = &speex_uwb_mode;
86 +      mode3 = speex_mode_new (SPEEX_MODEID_UWB);
87
88      Constructed modes must be destroyed after use:
89
90 +      speex_mode_destroy (mode1);
91 +      speex_mode_destroy (mode2);
92 +      speex_mode_destroy (mode3);
93
94      Note that the constants SPEEX_MODEID_NB, SPEEX_MODEID_WB and
95      SPEEX_MODEID_UWB were introduced in libspeex 1.1.6, and are
96      defined in <speex/speex.h>.
97
98   3. It is fairly easy to conditionally build an application for either
99      usage of the libspeex API. For example using GNU Autoconf, you can
100      check for the existence of a symbol such as speex_mode_new in
101      configure.ac. The following example is from libfishsound[2]:
102
103     dnl Test for libspeex SPEEX_DISABLE_GLOBAL_POINTERS API
104     dnl If so, we need to use a different API to access available modes,
105     dnl and free them after use.
106     AC_CHECK_LIB(speex, speex_mode_new, DISABLE_GLOBAL_POINTERS="yes",
107       DISABLE_GLOBAL_POINTERS="no")
108     if test "x$DISABLE_GLOBAL_POINTERS" = xyes ; then
109       AC_DEFINE(SPEEX_DISABLE_GLOBAL_POINTERS, ,
110        [Define if libspeex uses SPEEX_DISABLE_GLOBAL_POINTERS API])
111     fi
112
113
114 References
115 ----------
116
117 [1] http://www.symbian.com/developer/techlib/papers/coding_idioms/2002_10_09_codingSymbianOS.pdf
118
119 [2] http://www.annodex.net/software/libfishsound/
120