Max 5 API Reference
00001 // ext_itm.h copyright 2008 cycling '74 all rights reserved 00002 00003 #ifndef __EXT_ITM_H__ 00004 #define __EXT_ITM_H__ 00005 00006 BEGIN_USING_C_LINKAGE 00007 00008 00009 /** A low-level object for tempo-based scheduling. 00010 @ingroup time 00011 @see #t_timeobject 00012 @see @ref chapter_itm */ 00013 typedef t_object t_itm; 00014 00015 00016 // private -- internal use only 00017 typedef struct _clocksource 00018 { 00019 t_object c_ob; 00020 method c_getticks; // returns the current tick count 00021 method c_getstate; // returns 0 if transport not going, 1 if going 00022 t_symbol *c_name; // name 00023 long c_usedcount; // number of transports using this clock source 00024 } t_clocksource; 00025 00026 00027 /** Flags that determine attribute and time object behavior 00028 @ingroup time */ 00029 enum { 00030 TIME_FLAGS_LOCATION = 1, ///< 1 1 0 location-based bar/beat/unit values (as opposed to interval values, which are 0 0 0 relative) 00031 TIME_FLAGS_TICKSONLY = 2, ///< only ticks-based values (not ms) are acceptable 00032 TIME_FLAGS_FIXEDONLY = 4, ///< only fixed values (ms, hz, samples) are acceptable 00033 TIME_FLAGS_LOOKAHEAD = 8, ///< add lookahead attribute (unsupported) 00034 TIME_FLAGS_USECLOCK = 16, ///< this time object will schedule events, not just hold a value 00035 TIME_FLAGS_USEQELEM = 32, ///< this time object will defer execution of scheduled events to low priority thread 00036 TIME_FLAGS_FIXED = 64, ///< will only use normal clock (i.e., will never execute out of ITM) 00037 TIME_FLAGS_PERMANENT = 128, ///< event will be scheduled in the permanent list (tied to a specific time) 00038 TIME_FLAGS_TRANSPORT = 256, ///< add a transport attribute 00039 TIME_FLAGS_EVENTLIST = 512, ///< add an eventlist attribute (unsupported) 00040 TIME_FLAGS_CHECKSCHEDULE = 1024, ///< internal use only 00041 TIME_FLAGS_LISTENTICKS = 2048, ///< flag for time_listen: only get notifications if the time object holds tempo-relative values 00042 TIME_FLAGS_NOUNITS = 4096, ///< internal use only 00043 TIME_FLAGS_BBUSOURCE = 8192, ///< source time was in bar/beat/unit values, need to recalculate when time sig changes 00044 TIME_FLAGS_POSITIVE = 16384 ///< constrain any values < 0 to 0 00045 }; 00046 00047 00048 /*******************************************************************************/ 00049 00050 /** Return the global (default / unnamed) itm object. 00051 @ingroup time 00052 @return The global #t_itm object. */ 00053 void *itm_getglobal(void); 00054 00055 /** Return a named itm object. 00056 @ingroup time 00057 @param s The name of the itm to return. 00058 @param create If non-zero, then create this named itm should it not already exist. 00059 @return The global #t_itm object. */ 00060 void *itm_getnamed(t_symbol *s, long create); 00061 00062 // currently the same as itm_getnamed(s,true); 00063 void *itm_getfromarg(t_object *o, t_symbol *s); 00064 00065 /** Reference an itm object. 00066 When you are using an itm object, you must call this function to increment its reference count. 00067 @ingroup time 00068 @param x The itm object. */ 00069 void itm_reference(t_itm *x); 00070 00071 /** Stop referencing an itm object. 00072 When you are done using an itm object, you must call this function to decrement its reference count. 00073 @ingroup time 00074 @param x The itm object. */ 00075 void itm_dereference(t_itm *x); 00076 00077 00078 // event list support is limited to use in javascript for the time being. 00079 void itm_deleteeventlist(t_itm *x, t_symbol *eventlist); 00080 void itm_eventlistseek(t_itm *x); 00081 void itm_geteventlistnames(t_itm *x, long *count, t_symbol ***names); 00082 void itm_switcheventlist(t_itm *x, t_symbol *eventlist, double offset); 00083 00084 00085 /** Report the current internal time. 00086 This is the same as calling clock_getftime(); 00087 @ingroup time 00088 @param x The itm object. 00089 @return The current internal time. */ 00090 double itm_gettime(t_itm *x); 00091 00092 /** Report the current time of the itm in ticks. 00093 You can use functions such as itm_tickstobarbeatunits() or itm_tickstoms() to convert to a different representation of the time. 00094 @ingroup time 00095 @param x The itm object. 00096 @return The current time in ticks. */ 00097 double itm_getticks(t_itm *x); 00098 00099 /** Print diagnostic information about an itm object to the Max window. 00100 @ingroup time 00101 @param x The itm object. */ 00102 void itm_dump(t_itm *x); 00103 00104 00105 // private -- internal use only 00106 void itm_sync(t_itm *x); 00107 00108 00109 00110 /** Set an itm object's current time signature. 00111 @ingroup time 00112 @param x The itm object. 00113 @param num The top number of the time signature. 00114 @param denom The bottom number of the time signature. 00115 @param flags Currently unused -- pass zero. */ 00116 void itm_settimesignature(t_itm *x, long num, long denom, long flags); 00117 00118 /** Query an itm object for its current time signature. 00119 @ingroup time 00120 @param x The itm object. 00121 @param num The address of a variable to hold the top number of the time signature upon return. 00122 @param denom The address of a variable to hold the bottom number of the time signature upon return. */ 00123 void itm_gettimesignature(t_itm *x, long *num, long *denom); 00124 00125 void itm_seek(t_itm *x, double oldticks, double newticks, long chase); 00126 00127 /** Pause the passage of time for an itm object. 00128 This is the equivalent to setting the state of a transport object to 0 with a toggle. 00129 @ingroup time 00130 @param x The itm object. */ 00131 void itm_pause(t_itm *x); 00132 00133 /** Start the passage of time for an itm object, from it's current location. 00134 This is the equivalent to setting the state of a transport object to 0 with a toggle. 00135 @ingroup time 00136 @param x The itm object. */ 00137 void itm_resume(t_itm *x); 00138 00139 /** Find out if time is currently progressing for a given itm object. 00140 @ingroup time 00141 @param x The itm object. 00142 @return Returns non-zero if the time is running, or zero if it is paused. 00143 @see itm_pause() 00144 @see itm_resume() */ 00145 long itm_getstate(t_itm *x); 00146 00147 00148 /** Set the number of ticks-per-quarter-note globally for the itm system. 00149 The default is 480. 00150 @ingroup time 00151 @param res The number of ticks-per-quarter-note. 00152 @see itm_getresolution() */ 00153 void itm_setresolution(double res); 00154 00155 /** Get the number of ticks-per-quarter-note globally from the itm system. 00156 @ingroup time 00157 @return The number of ticks-per-quarter-note. 00158 @see itm_setresolution() */ 00159 double itm_getresolution(void); 00160 00161 00162 /** Given an itm object, return its name. 00163 @ingroup time 00164 @param x The itm object. 00165 @return The name of the itm. */ 00166 t_symbol *itm_getname(t_itm *x); 00167 00168 00169 00170 t_max_err itm_parse(t_itm *x, long argc, t_atom *argv, long flags, double *ticks, double *fixed, t_symbol **unit, long *bbu, char *bbusource); 00171 00172 00173 /** Convert a time value in ticks to the equivalent value in milliseconds, given the context of a specified itm object. 00174 @ingroup time 00175 @param x An itm object. 00176 @param ticks A time specified in ticks. 00177 @return The time specified in ms. */ 00178 double itm_tickstoms(t_itm *x, double ticks); 00179 00180 /** Convert a time value in milliseconds to the equivalent value in ticks, given the context of a specified itm object. 00181 @ingroup time 00182 @param x An itm object. 00183 @param ms A time specified in ms. 00184 @return The time specified in ticks. */ 00185 double itm_mstoticks(t_itm *x, double ms); 00186 00187 /** Convert a time value in milliseconds to the equivalent value in samples, given the context of a specified itm object. 00188 @ingroup time 00189 @param x An itm object. 00190 @param ms A time specified in ms. 00191 @return The time specified in samples. */ 00192 double itm_mstosamps(t_itm *x, double ms); 00193 00194 /** Convert a time value in samples to the equivalent value in milliseconds, given the context of a specified itm object. 00195 @ingroup time 00196 @param x An itm object. 00197 @param samps A time specified in samples. 00198 @return The time specified in ms. */ 00199 double itm_sampstoms(t_itm *x, double samps); 00200 00201 00202 /** Convert a time value in bbu to the equivalent value in ticks, given the context of a specified itm object. 00203 @ingroup time 00204 @param x An itm object. 00205 @param bars The measure number of the location/position. 00206 @param beats The beat number of the location/position. 00207 @param units The number of ticks past the beat of the location/position. 00208 @param ticks The address of a variable to hold the number of ticks upon return. 00209 @param position Set this parameter to #TIME_FLAGS_LOCATION or to zero (for position mode). */ 00210 void itm_barbeatunitstoticks(t_itm *x, long bars, long beats, double units, double *ticks, char position); 00211 00212 /** Convert a time value in bbu to the equivalent value in ticks, given the context of a specified itm object. 00213 @ingroup time 00214 @param x An itm object. 00215 @param ticks The number of ticks to translate into a time represented as bars, beats, and ticks. 00216 @param bars The address of a variable to hold the measure number of the location/position upon return. 00217 @param beats The address of a variable to hold the beat number of the location/position upon return. 00218 @param units The address of a variable to hold the number of ticks past the beat of the location/position upon return. 00219 @param position Set this parameter to #TIME_FLAGS_LOCATION or to zero (for position mode). */ 00220 void itm_tickstobarbeatunits(t_itm *x, double ticks, long *bars, long *beats, double *units, char position); 00221 00222 00223 void itm_format(t_itm *x, double ms, double ticks, long flags, t_symbol *unit, long *argc, t_atom **argv); 00224 00225 00226 /** Given the name of a time unit (e.g. 'ms', 'ticks', 'bbu', 'samples', etc.), determine whether the unit is fixed 00227 (doesn't change with tempo, time-signature, etc.) or whether it is flexible. 00228 @ingroup time 00229 @param u The name of the time unit. 00230 @return Zero if the unit is fixed (milliseconds, for example) or non-zero if it is flexible (ticks, for example). */ 00231 long itm_isunitfixed(t_symbol *u); 00232 00233 00234 00235 void itmclock_delay(t_object *x, t_itm *m, t_symbol *eventlist, double delay, long quantization); 00236 void *itmclock_new(t_object *owner, t_object *timeobj, method task, method killer, long permanent); 00237 void itmclock_set(t_object *x, t_itm *m, t_symbol *eventlist, double time); 00238 void itmclock_unset(t_object *x); 00239 00240 00241 // private -- internal use only 00242 void *itm_clocksource_getnamed(t_symbol *name, long create); 00243 void itm_getclocksources(long *count, t_symbol ***sources); 00244 00245 00246 END_USING_C_LINKAGE 00247 00248 #endif // __EXT_ITM_H__
Copyright © 2008, Cycling '74