Max 5 API Reference
00001 /* 00002 * ext_time.h 00003 * 00004 * Copyright 2008 Cycling '74. All rights reserved. 00005 * 00006 */ 00007 00008 #ifndef __EXT_TIME_H__ 00009 #define __EXT_TIME_H__ 00010 00011 #include "ext_itm.h" 00012 00013 BEGIN_USING_C_LINKAGE 00014 00015 00016 00017 /** 00018 A high-level time object for tempo-based scheduling. 00019 00020 @ingroup time 00021 @see #t_itm 00022 @see @ref chapter_itm 00023 */ 00024 typedef t_object t_timeobject; 00025 00026 00027 /*******************************************************************************/ 00028 00029 00030 /** 00031 Stop a currently scheduled time object. 00032 00033 @ingroup time 00034 @param x The time object. 00035 00036 */ 00037 void time_stop(t_timeobject *x); 00038 00039 00040 /** 00041 Execute a time object's task, then if it was already set to execute, reschedule for the current interval value of the object. 00042 00043 @ingroup time 00044 @param x The time object. 00045 00046 */ 00047 void time_tick(t_timeobject *x); 00048 00049 00050 /** 00051 Convert the value of a time object to milliseconds. 00052 00053 @ingroup time 00054 @param x The time object. 00055 @return The time object's value, converted to milliseconds. 00056 */ 00057 double time_getms(t_timeobject *x); 00058 00059 00060 /** 00061 Convert the value of a time object to ticks. 00062 00063 @ingroup time 00064 @param x The time object. 00065 @return The time object's value, converted to ticks. 00066 */ 00067 double time_getticks(t_timeobject *x); 00068 00069 00070 /** 00071 Return the phase of the ITM object (transport) associated with a time object. 00072 00073 @ingroup time 00074 @param tx The time object. 00075 @param phase Pointer to a double to receive the progress within the specified time value of the associated ITM object. 00076 @param slope Pointer to a double to receive the slope (phase difference) within the specified time value of the associated ITM object. 00077 */ 00078 void time_getphase(t_timeobject *tx, double *phase, double *slope); 00079 00080 00081 /** 00082 Specify that a millisecond-based attribute to be updated automatically when the converted milliseconds of the time object's value changes. 00083 00084 @ingroup time 00085 @param x The time object. 00086 @param attr Name of the millisecond based attribute in the owning object that will be updated 00087 @param flags If TIME_FLAGS_LISTENTICKS is passed here, updating will not happen if the time value is fixed (ms) based 00088 */ 00089 void time_listen(t_timeobject *x, t_symbol *attr, long flags); 00090 00091 00092 /** 00093 Set the current value of a time object (either an interval or a position) using a Max message. 00094 00095 @ingroup time 00096 @param tx The time object. 00097 @param s Message selector. 00098 @param argc Count of arguments. 00099 @param argv Message arguments. 00100 */ 00101 void time_setvalue(t_timeobject *tx, t_symbol *s, long argc, t_atom *argv); 00102 00103 /** 00104 Create an attribute permitting a time object to be changed in a user-friendly way. 00105 00106 @ingroup time 00107 @param c Class being initialized. 00108 @param attrname Name of the attribute associated with the time object. 00109 @param attrlabel Descriptive label for the attribute (appears in the inspector) 00110 @param flags Options, see "Flags that determine time object behavior" above 00111 */ 00112 void class_time_addattr(t_class *c, char *attrname, char *attrlabel, long flags); 00113 00114 /** 00115 Create a new time object. 00116 00117 @ingroup time 00118 @param owner Object that will own this time object (task routine, if any, will pass owner as argument). 00119 @param attrname Name of the attribute associated with the time object. 00120 @param tick Task routine that will be executed (can be NULL) 00121 @param flags Options, see "Flags that determine time object behavior" above 00122 @return The newly created #t_timeobject. 00123 */ 00124 void *time_new(t_object *owner, t_symbol *attrname, method tick, long flags); 00125 00126 /** 00127 Return a time object associated with an attribute of an owning object. 00128 00129 @ingroup time 00130 @param owner Object that owns this time object (task routine, if any, will pass owner as argument). 00131 @param attrname Name of the attribute associated with the time object. 00132 @return The #t_timeobject associated with the named attribute. 00133 */ 00134 t_object *time_getnamed(t_object *owner, t_symbol *attrname); 00135 00136 00137 void time_enable_attributes(t_object *x); 00138 00139 /** 00140 Return whether this time object currently holds a fixed (millisecond-based) value. 00141 00142 @ingroup time 00143 @param x Time object. 00144 @return True if time object's current value is fixed, false if it is tempo-relative. 00145 */ 00146 long time_isfixedunit(t_timeobject *x); 00147 00148 00149 /** 00150 Schedule a task, with optional quantization. 00151 00152 @ingroup time 00153 @param x The time object that schedules temporary events (must have been created with TIME_FLAGS_USECLOCK but not TIME_FLAGS_PERMANENT) 00154 @param quantize A time object that holds a quantization interval, can be NULL for no quantization. 00155 */ 00156 void time_schedule(t_timeobject *x, t_timeobject *quantize); 00157 00158 00159 /** 00160 Schedule a task, with optional minimum interval, 00161 00162 @ingroup time 00163 @param x The time object that schedules temporary events (must have been created with TIME_FLAGS_USECLOCK but not TIME_FLAGS_PERMANENT) 00164 @param quantize The minimum interval into the future when the event can occur, can be NULL if there is no minimum interval. 00165 */ 00166 void time_schedule_limit(t_timeobject *x, t_timeobject *quantize); 00167 00168 /** 00169 Schedule a task for right now, with optional quantization. 00170 00171 @ingroup time 00172 @param x The time object that schedules temporary events. The time interval is ignored and 0 ticks is used instead. 00173 @param quantize A time object that holds a quantization interval, can be NULL for no quantization. 00174 */ 00175 void time_now(t_timeobject *x, t_timeobject *quantize); 00176 00177 00178 /** 00179 Return the ITM object associated with this time object. 00180 00181 @ingroup time 00182 @param ox Time object. 00183 @return The associated #t_itm object. 00184 */ 00185 void *time_getitm(t_timeobject *ox); 00186 00187 00188 /** 00189 Calculate the quantized interval (in ticks) if this time object were to be scheduled at the current time. 00190 00191 @ingroup time 00192 @param ox Time object. 00193 @param vitm The associated ITM object (use time_getitm() to determine it). 00194 @param oq A time object that holds a quantization interval, can be NULL. 00195 @return Interval (in ticks) for scheduling this object. 00196 */ 00197 double time_calcquantize(t_timeobject *ox, t_itm *vitm, t_timeobject *oq); 00198 00199 00200 /** 00201 Associate a named setclock object with a time object (unsupported). 00202 00203 @ingroup time 00204 @param tx Time object. 00205 @param sc Name of an associated setclock object. 00206 */ 00207 void time_setclock(t_timeobject *tx, t_symbol *sc); 00208 00209 END_USING_C_LINKAGE 00210 00211 #endif // __EXT_TIME_H__ 00212
Copyright © 2008, Cycling '74