add note about --disable-global-pointers to README.symbian
[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 document outlines how to build libspeex for Symbian OS, and how to
17 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
40 Developing applications for libspeex modified for Symbian OS
41 ------------------------------------------------------------
42
43 The only part of the libspeex API which has been modified for Symbian OS,
44 and thus affects user code which links against libspeex, is the removal of
45 statically defined SpeexMode structures: speex_nb_mode, speex_wb_mode,
46 speex_uwb_mode, and the array speex_mode_list[]. All other aspects of
47 application development using the libspeex API remain unchanged.
48
49
50   1. applications must additionally include the header:
51
52 +    #include <speex_noglobals.h>
53
54
55   2. any references to the statically defined SpeexMode structures must be
56      replaced by a call to a constructor for that mode; and the
57      constructed mode must later be free'd appropriately.
58
59      * References to the statically defined array speex_mode_list[modeID]
60      must be replaced by a call to speex_mode_new_byID (modeID):
61
62 -      mode = speex_mode_list[modeID];
63 +      mode = speex_mode_new_byID (modeID);
64
65      and later free'd:
66
67 +      speex_mode_free_byID (mode, modeID);
68
69      note that you must remember the association between a constructed
70      mode and its modeID in order to correctly free it later. Failure to
71      do so may introduce memory leaks or runtime errors.
72
73      * References to the statically defined mode structures must be replaced:
74
75        SpeexMode * mode1, * mode2, * mode3;
76
77 -      mode1 = &speex_nb_mode;
78 +      mode1 = speex_nb_mode_new ();
79
80 -      mode2 = &speex_wb_mode;
81 +      mode2 = speex_wb_mode_new ();
82
83 -      mode3 = &speex_uwb_mode;
84 +      mode3 = speex_uwb_mode_new ();
85
86      Constructed modes must be free'd after use:
87
88 +      speex_nb_mode_free (mode1);
89 +      speex_wb_mode_free (mode2);
90 +      speex_uwb_mode_free (mode3);
91
92
93   3. It is fairly easy to conditionally build an application for either
94      usage of the libspeex API. For example using GNU Autoconf, you can
95      check for the existence of a symbol such as speex_mode_new_byID in
96      configure.ac. The following example is from libfishsound[2]:
97
98     dnl Test for libspeex SPEEX_DISABLE_GLOBAL_POINTERS API
99     dnl If so, we need to use a different API to access available modes,
100     dnl and free them after use.
101     AC_CHECK_LIB(speex, speex_mode_new_byID, DISABLE_GLOBAL_POINTERS="yes",
102       DISABLE_GLOBAL_POINTERS="no")
103     if test "x$DISABLE_GLOBAL_POINTERS" = xyes ; then
104       AC_DEFINE(SPEEX_DISABLE_GLOBAL_POINTERS, ,
105        [Define if libspeex uses SPEEX_DISABLE_GLOBAL_POINTERS API])
106     fi
107
108
109 References
110 ----------
111
112 [1] http://www.symbian.com/developer/techlib/papers/coding_idioms/2002_10_09_codingSymbianOS.pdf
113
114 [2] http://www.annodex.net/software/libfishsound/
115