1 /*
2     csmodule.h:
3 
4     Copyright (C) 2005 Istvan Varga
5     based on dl_opcodes.c, Copyright (C) 2002 John ffitch
6 
7     This file is part of Csound.
8 
9     The Csound Library is free software; you can redistribute it
10     and/or modify it under the terms of the GNU Lesser General Public
11     License as published by the Free Software Foundation; either
12     version 2.1 of the License, or (at your option) any later version.
13 
14     Csound is distributed in the hope that it will be useful,
15     but WITHOUT ANY WARRANTY; without even the implied warranty of
16     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
17     GNU Lesser General Public License for more details.
18 
19     You should have received a copy of the GNU Lesser General Public
20     License along with Csound; if not, write to the Free Software
21     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
22     02110-1301 USA
23 */
24 
25 #ifndef CSOUND_CSMODULE_H
26 #define CSOUND_CSMODULE_H
27 
28 /******************************************************************************
29  * NEW PLUGIN INTERFACE                                                       *
30  * ====================                                                       *
31  *                                                                            *
32  * Plugin libraries are loaded from the directory defined by the environment  *
33  * variable OPCODE6DIR (or the current directory if OPCODE6DIR is unset) by   *
34  * csoundPreCompile() while initialising a Csound instance, and are unloaded  *
35  * at the end of performance by csoundReset().                                *
36  * A library may export any of the following five interface functions,        *
37  * however, the presence of csoundModuleCreate() is required for identifying  *
38  * the file as a Csound plugin module.                                        *
39  *                                                                            *
40  * int csoundModuleCreate(CSOUND *csound)       (required)                    *
41  * --------------------------------------                                     *
42  *                                                                            *
43  * Pre-initialisation function, called by csoundPreCompile().                 *
44  *                                                                            *
45  * int csoundModuleInit(CSOUND *csound)         (optional)                    *
46  * ------------------------------------                                       *
47  *                                                                            *
48  * Called by Csound instances before orchestra translation. One possible use  *
49  * of csoundModuleInit() is adding new opcodes with csoundAppendOpcode().     *
50  *                                                                            *
51  * int csoundModuleDestroy(CSOUND *csound)      (optional)                    *
52  * ---------------------------------------                                    *
53  *                                                                            *
54  * Destructor function for Csound instance 'csound', called at the end of     *
55  * performance, after closing audio output.                                   *
56  *                                                                            *
57  * const char *csoundModuleErrorCodeToString(int errcode)   (optional)        *
58  * ------------------------------------------------------                     *
59  *                                                                            *
60  * Converts error codes returned by any of the initialisation or destructor   *
61  * functions to a string message.                                             *
62  *                                                                            *
63  * int csoundModuleInfo(void)                   (optional)                    *
64  * --------------------------                                                 *
65  *                                                                            *
66  * Returns information that can be used to determine if the plugin was built  *
67  * for a compatible version of libcsound. The return value may be the sum of  *
68  * any of the following two values:                                           *
69  *                                                                            *
70  *   ((CS_APIVERSION << 16) + (CS_APISUBVER << 8))      API version           *
71  *   (int) sizeof(MYFLT)                                MYFLT type            *
72  *                                                                            *
73  ******************************************************************************/
74 
75 #ifdef __cplusplus
76 extern "C" {
77 #endif
78 
79   /* ------------------------ INTERNAL API FUNCTIONS ------------------------ */
80 
81   /**
82    * Load plugin libraries for Csound instance 'csound', and call
83    * pre-initialisation functions.
84    * Return value is CSOUND_SUCCESS if there was no error, CSOUND_ERROR if
85    * some modules could not be loaded or initialised, and CSOUND_MEMORY
86    * if a memory allocation failure has occured.
87    */
88   int csoundLoadModules(CSOUND *csound);
89 
90   /**
91    * Call initialisation functions of all loaded modules that have a
92    * csoundModuleInit symbol, for Csound instance 'csound'.
93    * Return value is CSOUND_SUCCESS if there was no error, and CSOUND_ERROR if
94    * some modules could not be initialised.
95    */
96   int csoundInitModules(CSOUND *csound);
97 
98   /** Load and initialise all modules from one directory
99    */
100   int csoundLoadAndInitModules(CSOUND *csound, const char *opdir);
101 
102   /**
103    * Call destructor functions of all loaded modules that have a
104    * csoundModuleDestroy symbol, for Csound instance 'csound'.
105    * Return value is CSOUND_SUCCESS if there was no error, and
106    * CSOUND_ERROR if some modules could not be de-initialised.
107    */
108   int csoundDestroyModules(CSOUND *csound);
109 
110   /**
111    * Initialise opcodes not in entry1.c
112    */
113   int csoundInitSaticModules(CSOUND *csound);
114 
115 #ifdef __cplusplus
116 }
117 #endif
118 
119 #endif /* CSOUND_CSMODULE_H */
120 
121