Max 5 API Reference
00001 // z_dsp.h -- the main header file for all DSP objects copyright 1997-2003 Cycling '74 00002 00003 // DSP services: 00004 00005 #ifndef _Z_DSP_H 00006 #define _Z_DSP_H 00007 00008 #ifndef SAMPLE_TYPEDEF 00009 /** An integer. @ingroup msp */ 00010 typedef int t_int; 00011 /** A float. @ingroup msp */ 00012 typedef float t_float; 00013 /** A sample value. @ingroup msp */ 00014 typedef float t_sample; 00015 #define SAMPLE_TYPEDEF 00016 #endif 00017 00018 #include "z_altivec.h" 00019 00020 #if C74_PRAGMA_STRUCT_PACKPUSH 00021 #pragma pack(push, 2) 00022 #elif C74_PRAGMA_STRUCT_PACK 00023 #pragma pack(2) 00024 #endif 00025 00026 /** MSP System Properties. 00027 @ingroup msp */ 00028 enum { 00029 SYS_MAXBLKSIZE = 2048, ///< a good number for a maximum signal vector size 00030 SYS_MAXSIGS = 250 ///< number of signal inlets you can have in an object 00031 }; 00032 00033 // macro loop for checking for NAN/INF 00034 00035 // note: this may be platform-dependent 00036 00037 #define NAN_MASK 0x7F800000 00038 00039 #define NAN_CHECK(n,o) \ 00040 while (n--) { if ((*(o) & NAN_MASK) == NAN_MASK) *(o) = 0; (o)++; } // now post inc/dec -Rd jun 05 00041 00042 #define IS_DENORM_FLOAT(v) ((((*(unsigned long *)&(v))&0x7f800000)==0)&&((v)!=0.f)) 00043 #define IS_DENORM_DOUBLE(v) ((((((unsigned long *)&(v))[1])&0x7fe00000)==0)&&((v)!=0.)) 00044 00045 #define IS_NAN_FLOAT(v) (((*(unsigned long *)&(v))&0x7f800000)==0x7f800000) 00046 #define IS_NAN_DOUBLE(v) (((((unsigned long *)&(v))[1])&0x7fe00000)==0x7fe00000) 00047 00048 #define IS_DENORM_NAN_FLOAT(v) (IS_DENORM_FLOAT(v)||IS_NAN_FLOAT(v)) 00049 #define IS_DENORM_NAN_DOUBLE(v) (IS_DENORM_DOUBLE(v)||IS_NAN_DOUBLE(v)) 00050 00051 // currently all little endian processors are x86 00052 #if defined(WIN_VERSION) || (defined(MAC_VERSION)&&TARGET_RT_LITTLE_ENDIAN) 00053 #define DENORM_WANT_FIX 1 00054 #endif 00055 00056 #ifdef DENORM_WANT_FIX 00057 00058 #define FIX_DENORM_FLOAT(v) ((v)=IS_DENORM_FLOAT(v)?0.f:(v)) 00059 #define FIX_DENORM_DOUBLE(v) ((v)=IS_DENORM_DOUBLE(v)?0.f:(v)) 00060 00061 #define FIX_DENORM_NAN_FLOAT(v) ((v)=IS_DENORM_NAN_FLOAT(v)?0.f:(v)) 00062 #define FIX_DENORM_NAN_DOUBLE(v) ((v)=IS_DENORM_NAN_DOUBLE(v)?0.:(v)) 00063 00064 #else 00065 00066 #define FIX_DENORM_FLOAT(v) 00067 #define FIX_DENORM_DOUBLE(v) 00068 00069 #define FIX_DENORM_NAN_FLOAT(v) 00070 #define FIX_DENORM_NAN_DOUBLE(v) 00071 00072 #endif 00073 00074 00075 // header for all DSP objects. Provides a proxy. 00076 00077 // z_misc flags: 00078 00079 #define Z_NO_INPLACE 1 ///< flag indicating the object doesn't want signals in place @ingroup msp 00080 #define Z_PUT_LAST 2 ///< when list of ugens is resorted, put this object at end @ingroup msp 00081 #define Z_PUT_FIRST 4 ///< when list of ugens is resorted, put this object at beginning @ingroup msp 00082 00083 typedef void *t_proxy; 00084 00085 /** Header for any non-ui signal processing object. 00086 For ui objects use #t_pxjbox. 00087 @ingroup msp */ 00088 typedef struct t_pxobject { 00089 struct object z_ob; ///< The standard #t_object struct. 00090 long z_in; 00091 #ifdef PROBE_TEST 00092 void *z_proxy; 00093 #else 00094 t_proxy *z_proxy; 00095 #endif 00096 long z_disabled; ///< set to non-zero if this object is muted (using the pcontrol or mute~ objects) 00097 short z_count; ///< an array that indicates what inlets/outlets are connected with signals 00098 short z_misc; ///< flags (bitmask) determining object behaviour, such as #Z_NO_INPLACE, #Z_PUT_FIRST, or #Z_PUT_LAST 00099 } t_pxobject; 00100 00101 00102 #define MAXLOGSIG 13 00103 #define MAXSIGSIZE (1 << MAXLOGSIG) 00104 /** The signal data structure. 00105 @ingroup msp */ 00106 typedef struct _signal 00107 { 00108 long s_n; ///< The vector size of the signal. 00109 t_sample *s_vec; ///< An array of buffers holding the vectors of audio. 00110 float s_sr; ///< The sample rate of the signal. 00111 struct _signal *s_next; 00112 struct _signal *s_nextused; 00113 short s_refcount; 00114 short s_size; // element size (* s_n == memory) 00115 char *s_ptr; // what to free 00116 } t_signal; 00117 00118 00119 // c74 private 00120 00121 typedef struct _dspchain 00122 { 00123 t_object c_ob; 00124 t_int *c_chain; 00125 long c_chainsize; 00126 long c_callcount; 00127 long c_usedcount; 00128 long c_reusedcount; 00129 long c_freedcount; 00130 long c_sr; 00131 long c_bs; 00132 t_signal *c_usedlist; 00133 t_signal *c_freelist; 00134 t_signal *c_zero; 00135 struct _ugenbox *c_ugenlist; // temporary variable, allows reentrant compiling 00136 struct _dspchain *c_prev; 00137 void *c_patcher; // top-level parent or 0 if global 00138 void *c_inlets; // collection of inlets 00139 void *c_outlets; // collection of outlets 00140 void *c_inputs; // signal input list (zero before first exec) 00141 void *c_outputs; // signal output list 00142 // have to determine whether freelist is global or local 00143 long c_broken; // object being freed, don't run it 00144 long c_intype; // using old signal linklist (0) or array 00145 long c_outtype; // using old signal linklist (0) or array 00146 } t_dspchain; 00147 00148 /** A function pointer for the audio perform routine used by MSP objects to process blocks of samples. @ingroup msp */ 00149 typedef t_int *(*t_perfroutine)(t_int *args); 00150 00151 00152 #ifndef VPTR_TYPEDEF 00153 /** A void pointer. @ingroup msp */ 00154 typedef void *t_vptr; 00155 /** A void pointer. @ingroup msp */ 00156 typedef void *vptr; 00157 #define VPTR_TYPEDEF 00158 #endif 00159 00160 // useful define 00161 00162 #ifndef PI 00163 /** The pi constant. @ingroup msp */ 00164 #define PI 3.14159265358979323846 00165 #endif 00166 #ifndef TWOPI 00167 /** Twice the pi constant. @ingroup msp */ 00168 #define TWOPI 6.28318530717958647692 00169 #endif // TWOPI 00170 #ifndef PIOVERTWO 00171 /** Half of the pi constant. @ingroup msp */ 00172 #define PIOVERTWO 1.57079632679489661923 00173 #endif // PIOVERTWO 00174 00175 // system access prototypes 00176 00177 BEGIN_USING_C_LINKAGE 00178 00179 // messages to the dsp object 00180 00181 void *dspmess(t_symbol *mess); 00182 00183 // access to DSP system variables 00184 00185 /** Query MSP for the maximum global vector (block) size. 00186 @ingroup msp 00187 @return The maximum global vector size for the MSP environment. */ 00188 int sys_getmaxblksize(void); 00189 00190 /** Query MSP for the current global vector (block) size. 00191 @ingroup msp 00192 @return The current global vector size for the MSP environment. */ 00193 int sys_getblksize(void); 00194 00195 /** Query MSP for the global sample rate. 00196 @ingroup msp 00197 @return The global sample rate of the MSP environment. */ 00198 float sys_getsr(void); 00199 00200 int sys_getch(void); // returns current number of channels 00201 int sys_optimize(void); // returns whether to optimize or not 00202 int sys_altivec(void); // returns whether machine has vector processing 00203 00204 /** Query MSP to determine whether or not it is running. 00205 @ingroup msp 00206 @return Returns true if the DSP is turned on, otherwise returns false. */ 00207 int sys_getdspstate(void); // returns whether audio is on or off 00208 00209 // controlling the DSP 00210 00211 void canvas_start_dsp(void); 00212 void canvas_stop_dsp(void); 00213 void dsp_tick(void); // no longer used 00214 00215 // the dspchain object 00216 00217 t_dspchain *dspchain_start(long bs, long sr); 00218 t_dspchain *dspchain_get(void); 00219 t_dspchain *dspchain_compile(t_patcher *p, long bs, long sr); 00220 t_dspchain *dspchain_compile2(t_patcher *p, t_dspchain *x); 00221 void dspchain_tick(t_dspchain *c); 00222 void canvas_start_onedsp(t_patcher *p, t_dspchain **c, long bs, long sr); 00223 void canvas_stop_onedsp(t_dspchain *c); 00224 00225 // utility perform routines 00226 00227 void set_zero(float *dst, long n); 00228 t_int *plus_perform(t_int *args); 00229 t_int *sig_perform(t_int *args); 00230 t_int *copy_perform(t_int *args); 00231 t_int *plus2_perform(t_int *w); 00232 00233 // setup routines used by DSP objects 00234 00235 /** Call this function in your MSP object's dsp method. 00236 This function adds your object's perform method to the DSP call chain 00237 and specifies the arguments it will be passed. 00238 argc, the number of 00239 arguments to your perform method, should be followed by argc 00240 additional arguments, all of which must be the size of a pointer or a long. 00241 00242 @ingroup msp 00243 @param f The perform routine to use for processing audio. 00244 @param n The number of arguments that will follow 00245 @param ... The arguments that will be passed to the perform routine. */ 00246 void dsp_add(t_perfroutine f, int n, ...); 00247 00248 /** Call this function in your MSP object's dsp method. 00249 Use dsp_addv() to add your object's perform routine to the DSP call 00250 chain and specify its arguments in an array rather than as arguments to 00251 a function. 00252 00253 @ingroup msp 00254 @param f The perform routine to use for processing audio. 00255 @param n The number of arguments that will follow in the vector parameter. 00256 @param vector The arguments that will be passed to the perform routine. */ 00257 void dsp_addv(t_perfroutine f, int n, void **vector); 00258 00259 00260 /** Call this routine after creating your object in the new instance routine 00261 with object_alloc(). Cast your object to #t_pxobject as the first 00262 argument, then specify the number of signal inputs your object will 00263 have. dsp_setup() initializes fields of the #t_pxobject header and 00264 allocates any proxies needed (if num_signal_inputs is greater than 1). 00265 00266 Some signal objects have no inputs; you should pass 0 for 00267 num_signal_inputs in this case. After calling dsp_setup(), you can 00268 create additional non-signal inlets using intin(), floatin(), or 00269 inlet_new(). 00270 00271 @ingroup msp 00272 @param x Your object's pointer. 00273 @param nsignals The number of signal/proxy inlets to create for the object. 00274 @see #dsp_setup */ 00275 void z_dsp_setup(t_pxobject *x, long nsignals); // called in new method 00276 00277 /** This is commonly used rather than directly calling z_dsp_setup() in MSP objects. 00278 @ingroup msp */ 00279 #define dsp_setup z_dsp_setup 00280 00281 00282 /** This function disposes of any memory used by proxies allocated by 00283 dsp_setup(). It also notifies the signal compiler that the DSP call chain 00284 needs to be rebuilt if signal processing is active. You should be sure to 00285 call this before de-allocating any memory that might be in use by your 00286 object’s perform routine, in the event that signal processing is on when 00287 your object is freed. 00288 00289 @ingroup msp 00290 @param x The object to free. 00291 @see #dsp_free */ 00292 void z_dsp_free(t_pxobject *x); 00293 00294 /** This is commonly used rather than directly calling z_dsp_free() in MSP objects. 00295 @ingroup msp */ 00296 #define dsp_free z_dsp_free 00297 00298 00299 void z_add_signalmethod(void); // called in initialization routine 00300 #define dsp_initclass z_add_signalmethod 00301 00302 void z_sysinit(void); 00303 #define dsp_sysinit z_sysinit 00304 00305 void z_patcher_for_dsp(t_object *x); 00306 #define dsp_patcher z_patcher_for_dsp 00307 00308 void dsp_setpatcher(void *p); 00309 00310 short z_isconnected(t_object *x, t_object *dst, short *index); 00311 #define dsp_isconnected z_isconnected 00312 00313 short z_dsp_setloadupdate(short way); 00314 #define dsp_setloadupdate z_dsp_setloadupdate 00315 00316 void *dsp_setpostprocess(method pm); 00317 void *dsp_setpreprocess(method pm); 00318 00319 // used only by audio driver objects 00320 00321 void sys_setprocessflag(short way); 00322 00323 // lame audio file utility (do not use) 00324 00325 short aiff_parse(char *header, long *offset, long *size, long *nchans, long *ssize, 00326 long *srate, void *chunk, void *markers); 00327 00328 // memory utilities 00329 00330 void *t_resizebytes(char *old, long oldsize, long newsize); 00331 void *t_getbytes(long size); 00332 void *t_freebytes(void *fatso, long size); 00333 00334 // atom utilities 00335 00336 t_int atom_getintarg(short which, short argc, t_atom *argv); 00337 float atom_getfloatarg(short which, short argc, t_atom *argv); 00338 t_symbol *atom_getsymarg(short which, short argc, t_atom *argv); 00339 00340 #define PROXY_GETINLET(x) proxy_getinlet(x) 00341 00342 00343 /** This routine must be called in your object's initialization routine. It 00344 adds a set of methods to your object's class that are called by MSP to 00345 build the DSP call chain. These methods function entirely 00346 transparently to your object so you don't have to worry about them. 00347 However, you should avoid binding anything to their names: signal, 00348 drawline, userconnect, and enable. 00349 00350 This routine is for normal (non-user-interface objects). 00351 It must be called prior to calling class_register() for your class. 00352 00353 @ingroup msp 00354 @param c The class to make dsp-ready. 00355 @see class_dspinitbox() */ 00356 void class_dspinit(t_class *c); 00357 00358 /** This routine must be called in your object's initialization routine. It 00359 adds a set of methods to your object's class that are called by MSP to 00360 build the DSP call chain. These methods function entirely 00361 transparently to your object so you don't have to worry about them. 00362 However, you should avoid binding anything to their names: signal, 00363 drawline, userconnect, and enable. 00364 00365 This routine is for normal user-interface objects. 00366 00367 @ingroup msp 00368 @param c The class to make dsp-ready. 00369 @see class_dspinit() */ 00370 void class_dspinitbox(t_class *c); 00371 00372 00373 // defines for SIMD optimization 00374 00375 // minimum vector size to use SIMD optimization 00376 #define DSP_OPTIMIZE_MIN 64 00377 00378 // simple (e.g. times, minus) not worth optimizing, disabled 00379 #define DSP_SIMPLE_OPTIMIZE_TEST(sigptr) (FALSE) 00380 00381 // simple parameter setting test (e.g. times, minus) not worth optimizing, disabled 00382 #define DSP_SIMPLE_OPTIMIZE_TEST_PARAM (FALSE) 00383 00384 // complex (e.g. cos, log, sqrt, fft family) optimize as long as enabled and vector is large enough 00385 #define DSP_COMPLEX_OPTIMIZE_TEST(sigptr) (FALSE) 00386 //#define DSP_COMPLEX_OPTIMIZE_TEST(sigptr) (sys_optimize()&&(sigptr)&&(sigptr)->s_n>=DSP_OPTIMIZE_MIN) 00387 00388 // buffered routines optimize always if enabled since signal vector isn't relevant 00389 #define DSP_BUFFERED_OPTIMIZE_TEST(sigptr) (FALSE) 00390 //#define DSP_BUFFERED_OPTIMIZE_TEST(sigptr) (sys_optimize()) 00391 00392 00393 00394 END_USING_C_LINKAGE 00395 00396 #if C74_PRAGMA_STRUCT_PACKPUSH 00397 #pragma pack(pop) 00398 #elif C74_PRAGMA_STRUCT_PACK 00399 #pragma pack() 00400 #endif 00401 00402 //-- ddz, so this is OK, just needs jpatcher_api.h first, right? 00403 00404 #if defined(_JPATCHER_API_H_) || defined(_DOXY_) 00405 BEGIN_USING_C_LINKAGE 00406 00407 00408 /** Header for any ui signal processing object. 00409 For non-ui objects use #t_pxobject. 00410 @ingroup msp */ 00411 typedef struct _pxjbox { 00412 t_jbox z_box; ///< The box struct used by all ui objects. 00413 long z_in; 00414 #ifdef PROBE_TEST 00415 void *z_proxy; 00416 #else 00417 t_proxy *z_proxy; 00418 #endif 00419 long z_disabled; ///< set to non-zero if this object is muted (using the pcontrol or mute~ objects) 00420 short z_count; ///< an array that indicates what inlets/outlets are connected with signals 00421 short z_misc; ///< flags (bitmask) determining object behaviour, such as #Z_NO_INPLACE, #Z_PUT_FIRST, or #Z_PUT_LAST 00422 } t_pxjbox; 00423 00424 00425 /** Configure a class to be ready for use with the MSP signal chain. 00426 You must call this function when your class is initialized (typically in the main() function) 00427 for an object to process audio. 00428 @ingroup msp 00429 @param c The pointer to the class being configured. */ 00430 void class_dspinitjbox(t_class *c); 00431 00432 void z_jbox_dsp_setup(t_pxjbox *x, long nsignals); 00433 void z_jbox_dsp_free(t_pxjbox *x); 00434 00435 #define dsp_setupjbox z_jbox_dsp_setup 00436 #define dsp_freejbox z_jbox_dsp_free 00437 00438 END_USING_C_LINKAGE 00439 00440 00441 #endif // _JPATCHER_API_H_ 00442 #endif // _Z_DSP_H 00443
Copyright © 2008, Cycling '74