ITM Time Objects
[Timing]

ITM Time Objects are a high-level interface to ITM, a tempo-based scheduler API. More...

Collaboration diagram for ITM Time Objects:

Enumerations
enum	{   TIME_FLAGS_LOCATION = 1,   TIME_FLAGS_TICKSONLY = 2,   TIME_FLAGS_FIXEDONLY = 4,   TIME_FLAGS_LOOKAHEAD = 8,   TIME_FLAGS_USECLOCK = 16,   TIME_FLAGS_USEQELEM = 32,   TIME_FLAGS_FIXED = 64,   TIME_FLAGS_PERMANENT = 128,   TIME_FLAGS_TRANSPORT = 256,   TIME_FLAGS_EVENTLIST = 512,   TIME_FLAGS_CHECKSCHEDULE = 1024,   TIME_FLAGS_LISTENTICKS = 2048,   TIME_FLAGS_NOUNITS = 4096,   TIME_FLAGS_BBUSOURCE = 8192,   TIME_FLAGS_POSITIVE = 16384 }
	Flags that determine attribute and time object behavior. More...
Functions
void *	itm_getglobal (void)
	Return the global (default / unnamed) itm object.
void *	itm_getnamed (t_symbol *s, void *scheduler, t_symbol *defaultclocksourcename, long create)
	Return a named itm object.
void	itm_reference (t_itm *x)
	Reference an itm object.
void	itm_dereference (t_itm *x)
	Stop referencing an itm object.
double	itm_gettime (t_itm *x)
	Report the current internal time.
double	itm_getticks (t_itm *x)
	Report the current time of the itm in ticks.
void	itm_dump (t_itm *x)
	Print diagnostic information about an itm object to the Max window.
void	itm_settimesignature (t_itm *x, long num, long denom, long flags)
	Set an itm object's current time signature.
void	itm_gettimesignature (t_itm *x, long *num, long *denom)
	Query an itm object for its current time signature.
void	itm_pause (t_itm *x)
	Pause the passage of time for an itm object.
void	itm_resume (t_itm *x)
	Start the passage of time for an itm object, from it's current location.
long	itm_getstate (t_itm *x)
	Find out if time is currently progressing for a given itm object.
void	itm_setresolution (double res)
	Set the number of ticks-per-quarter-note globally for the itm system.
double	itm_getresolution (void)
	Get the number of ticks-per-quarter-note globally from the itm system.
t_symbol *	itm_getname (t_itm *x)
	Given an itm object, return its name.
double	itm_tickstoms (t_itm *x, double ticks)
	Convert a time value in ticks to the equivalent value in milliseconds, given the context of a specified itm object.
double	itm_mstoticks (t_itm *x, double ms)
	Convert a time value in milliseconds to the equivalent value in ticks, given the context of a specified itm object.
double	itm_mstosamps (t_itm *x, double ms)
	Convert a time value in milliseconds to the equivalent value in samples, given the context of a specified itm object.
double	itm_sampstoms (t_itm *x, double samps)
	Convert a time value in samples to the equivalent value in milliseconds, given the context of a specified itm object.
void	itm_barbeatunitstoticks (t_itm *x, long bars, long beats, double units, double *ticks, char position)
	Convert a time value in bbu to the equivalent value in ticks, given the context of a specified itm object.
void	itm_tickstobarbeatunits (t_itm *x, double ticks, long *bars, long *beats, double *units, char position)
	Convert a time value in bbu to the equivalent value in ticks, given the context of a specified itm object.
long	itm_isunitfixed (t_symbol *u)
	Given the name of a time unit (e.g.
void	time_stop (t_timeobject *x)
	Stop a currently scheduled time object.
void	time_tick (t_timeobject *x)
	Execute a time object's task, then if it was already set to execute, reschedule for the current interval value of the object.
double	time_getms (t_timeobject *x)
	Convert the value of a time object to milliseconds.
double	time_getticks (t_timeobject *x)
	Convert the value of a time object to ticks.
void	time_getphase (t_timeobject *tx, double *phase, double *slope, double *ticks)
	Return the phase of the ITM object (transport) associated with a time object.
void	time_listen (t_timeobject *x, t_symbol *attr, long flags)
	Specify that a millisecond-based attribute to be updated automatically when the converted milliseconds of the time object's value changes.
void	time_setvalue (t_timeobject *tx, t_symbol *s, long argc, t_atom *argv)
	Set the current value of a time object (either an interval or a position) using a Max message.
void	class_time_addattr (t_class *c, char *attrname, char *attrlabel, long flags)
	Create an attribute permitting a time object to be changed in a user-friendly way.
void *	time_new (t_object *owner, t_symbol *attrname, method tick, long flags)
	Create a new time object.
t_object *	time_getnamed (t_object *owner, t_symbol *attrname)
	Return a time object associated with an attribute of an owning object.
long	time_isfixedunit (t_timeobject *x)
	Return whether this time object currently holds a fixed (millisecond-based) value.
void	time_schedule (t_timeobject *x, t_timeobject *quantize)
	Schedule a task, with optional quantization.
void	time_schedule_limit (t_timeobject *x, t_timeobject *quantize)
	Schedule a task, with optional minimum interval,.
void	time_now (t_timeobject *x, t_timeobject *quantize)
	Schedule a task for right now, with optional quantization.
void *	time_getitm (t_timeobject *ox)
	Return the ITM object associated with this time object.
double	time_calcquantize (t_timeobject *ox, t_itm *vitm, t_timeobject *oq)
	Calculate the quantized interval (in ticks) if this time object were to be scheduled at the current time.
void	time_setclock (t_timeobject *tx, t_symbol *sc)
	Associate a named setclock object with a time object (unsupported).
Variables
BEGIN_USING_C_LINKAGE typedef t_object	t_itm
	A low-level object for tempo-based scheduling.
BEGIN_USING_C_LINKAGE typedef t_object	t_timeobject
	A high-level time object for tempo-based scheduling.

---

Detailed Description

ITM Time Objects are a high-level interface to ITM, a tempo-based scheduler API.

They provide an abtraction so your object can schedule events either in milliseconds (as traditional clock objects) or ticks (tempo-relative units).

---

Enumeration Type Documentation

anonymous enum

Flags that determine attribute and time object behavior.

Enumerator:

TIME_FLAGS_LOCATION	1 1 0 location-based bar/beat/unit values (as opposed to interval values, which are 0 0 0 relative)
TIME_FLAGS_TICKSONLY	only ticks-based values (not ms) are acceptable
TIME_FLAGS_FIXEDONLY	only fixed values (ms, hz, samples) are acceptable
TIME_FLAGS_LOOKAHEAD	add lookahead attribute (unsupported)
TIME_FLAGS_USECLOCK	this time object will schedule events, not just hold a value
TIME_FLAGS_USEQELEM	this time object will defer execution of scheduled events to low priority thread
TIME_FLAGS_FIXED	will only use normal clock (i.e., will never execute out of ITM)
TIME_FLAGS_PERMANENT	event will be scheduled in the permanent list (tied to a specific time)
TIME_FLAGS_TRANSPORT	add a transport attribute
TIME_FLAGS_EVENTLIST	add an eventlist attribute (unsupported)
TIME_FLAGS_CHECKSCHEDULE	internal use only
TIME_FLAGS_LISTENTICKS	flag for time_listen: only get notifications if the time object holds tempo-relative values
TIME_FLAGS_NOUNITS	internal use only
TIME_FLAGS_BBUSOURCE	source time was in bar/beat/unit values, need to recalculate when time sig changes
TIME_FLAGS_POSITIVE	constrain any values < 0 to 0

Definition at line 39 of file ext_itm.h.

---

Function Documentation

void class_time_addattr	(	t_class *	c,
		char *	attrname,
		char *	attrlabel,
		long	flags
	)

Create an attribute permitting a time object to be changed in a user-friendly way.

Parameters:

	c	Class being initialized.
	attrname	Name of the attribute associated with the time object.
	attrlabel	Descriptive label for the attribute (appears in the inspector)
	flags	Options, see "Flags that determine time object behavior" above

void itm_barbeatunitstoticks	(	t_itm *	x,
		long	bars,
		long	beats,
		double	units,
		double *	ticks,
		char	position
	)

Convert a time value in bbu to the equivalent value in ticks, given the context of a specified itm object.

Parameters:

	x	An itm object.
	bars	The measure number of the location/position.
	beats	The beat number of the location/position.
	units	The number of ticks past the beat of the location/position.
	ticks	The address of a variable to hold the number of ticks upon return.
	position	Set this parameter to TIME_FLAGS_LOCATION or to zero (for position mode).

void itm_dereference

(

t_itm *

x

)

Stop referencing an itm object.

When you are done using an itm object, you must call this function to decrement its reference count.

Parameters:

x

The itm object.

void itm_dump

(

t_itm *

x

)

Print diagnostic information about an itm object to the Max window.

Parameters:

x

The itm object.

void* itm_getglobal

(

void

)

Return the global (default / unnamed) itm object.

Returns:

The global t_itm object.

t_symbol* itm_getname

(

t_itm *

x

)

Given an itm object, return its name.

Parameters:

x

The itm object.

Returns:

The name of the itm.

void* itm_getnamed	(	t_symbol *	s,
		void *	scheduler,
		t_symbol *	defaultclocksourcename,
		long	create
	)

Return a named itm object.

Parameters:

	s	The name of the itm to return.
	scheduler
	defaultclocksourcename
	create	If non-zero, then create this named itm should it not already exist.

Returns:

The global t_itm object.

double itm_getresolution

(

void

)

Get the number of ticks-per-quarter-note globally from the itm system.

Returns:

The number of ticks-per-quarter-note.

See also:

itm_setresolution()

long itm_getstate

(

t_itm *

x

)

Find out if time is currently progressing for a given itm object.

Parameters:

x

The itm object.

Returns:

Returns non-zero if the time is running, or zero if it is paused.

See also:

itm_pause()

itm_resume()

double itm_getticks

(

t_itm *

x

)

Report the current time of the itm in ticks.

You can use functions such as itm_tickstobarbeatunits() or itm_tickstoms() to convert to a different representation of the time.

Parameters:

x

The itm object.

Returns:

The current time in ticks.

double itm_gettime

(

t_itm *

x

)

Report the current internal time.

This is the same as calling clock_getftime();

Parameters:

x

The itm object.

Returns:

The current internal time.

void itm_gettimesignature	(	t_itm *	x,
		long *	num,
		long *	denom
	)

Query an itm object for its current time signature.

Parameters:

	x	The itm object.
	num	The address of a variable to hold the top number of the time signature upon return.
	denom	The address of a variable to hold the bottom number of the time signature upon return.

long itm_isunitfixed

(

t_symbol *

u

)

Given the name of a time unit (e.g.

'ms', 'ticks', 'bbu', 'samples', etc.), determine whether the unit is fixed (doesn't change with tempo, time-signature, etc.) or whether it is flexible.

Parameters:

u

The name of the time unit.

Returns:

Zero if the unit is fixed (milliseconds, for example) or non-zero if it is flexible (ticks, for example).

double itm_mstosamps	(	t_itm *	x,
		double	ms
	)

Convert a time value in milliseconds to the equivalent value in samples, given the context of a specified itm object.

Parameters:

	x	An itm object.
	ms	A time specified in ms.

Returns:

The time specified in samples.

double itm_mstoticks	(	t_itm *	x,
		double	ms
	)

Convert a time value in milliseconds to the equivalent value in ticks, given the context of a specified itm object.

Parameters:

	x	An itm object.
	ms	A time specified in ms.

Returns:

The time specified in ticks.

void itm_pause

(

t_itm *

x

)

Pause the passage of time for an itm object.

This is the equivalent to setting the state of a transport object to 0 with a toggle.

Parameters:

x

The itm object.

void itm_reference

(

t_itm *

x

)

Reference an itm object.

When you are using an itm object, you must call this function to increment its reference count.

Parameters:

x

The itm object.

void itm_resume

(

t_itm *

x

)

Start the passage of time for an itm object, from it's current location.

This is the equivalent to setting the state of a transport object to 0 with a toggle.

Parameters:

x

The itm object.

double itm_sampstoms	(	t_itm *	x,
		double	samps
	)

Convert a time value in samples to the equivalent value in milliseconds, given the context of a specified itm object.

Parameters:

	x	An itm object.
	samps	A time specified in samples.

Returns:

The time specified in ms.

void itm_setresolution

(

double

res

)

Set the number of ticks-per-quarter-note globally for the itm system.

The default is 480.

Parameters:

res

The number of ticks-per-quarter-note.

See also:

itm_getresolution()

void itm_settimesignature	(	t_itm *	x,
		long	num,
		long	denom,
		long	flags
	)

Set an itm object's current time signature.

Parameters:

	x	The itm object.
	num	The top number of the time signature.
	denom	The bottom number of the time signature.
	flags	Currently unused -- pass zero.

void itm_tickstobarbeatunits	(	t_itm *	x,
		double	ticks,
		long *	bars,
		long *	beats,
		double *	units,
		char	position
	)

Convert a time value in bbu to the equivalent value in ticks, given the context of a specified itm object.

Parameters:

	x	An itm object.
	ticks	The number of ticks to translate into a time represented as bars, beats, and ticks.
	bars	The address of a variable to hold the measure number of the location/position upon return.
	beats	The address of a variable to hold the beat number of the location/position upon return.
	units	The address of a variable to hold the number of ticks past the beat of the location/position upon return.
	position	Set this parameter to TIME_FLAGS_LOCATION or to zero (for position mode).

double itm_tickstoms	(	t_itm *	x,
		double	ticks
	)

Convert a time value in ticks to the equivalent value in milliseconds, given the context of a specified itm object.

Parameters:

	x	An itm object.
	ticks	A time specified in ticks.

Returns:

The time specified in ms.

double time_calcquantize	(	t_timeobject *	ox,
		t_itm *	vitm,
		t_timeobject *	oq
	)

Calculate the quantized interval (in ticks) if this time object were to be scheduled at the current time.

Parameters:

	ox	Time object.
	vitm	The associated ITM object (use time_getitm() to determine it).
	oq	A time object that holds a quantization interval, can be NULL.

Returns:

Interval (in ticks) for scheduling this object.

void* time_getitm

(

t_timeobject *

ox

)

Return the ITM object associated with this time object.

Parameters:

ox

Time object.

Returns:

The associated t_itm object.

double time_getms

(

t_timeobject *

x

)

Convert the value of a time object to milliseconds.

Parameters:

x

The time object.

Returns:

The time object's value, converted to milliseconds.

t_object* time_getnamed	(	t_object *	owner,
		t_symbol *	attrname
	)

Return a time object associated with an attribute of an owning object.

Parameters:

	owner	Object that owns this time object (task routine, if any, will pass owner as argument).
	attrname	Name of the attribute associated with the time object.

Returns:

The t_timeobject associated with the named attribute.

void time_getphase	(	t_timeobject *	tx,
		double *	phase,
		double *	slope,
		double *	ticks
	)

Return the phase of the ITM object (transport) associated with a time object.

Parameters:

	tx	The time object.
	phase	Pointer to a double to receive the progress within the specified time value of the associated ITM object.
	slope	Pointer to a double to receive the slope (phase difference) within the specified time value of the associated ITM object.
	ticks

double time_getticks

(

t_timeobject *

x

)

Convert the value of a time object to ticks.

Parameters:

x

The time object.

Returns:

The time object's value, converted to ticks.

long time_isfixedunit

(

t_timeobject *

x

)

Return whether this time object currently holds a fixed (millisecond-based) value.

Parameters:

x

Time object.

Returns:

True if time object's current value is fixed, false if it is tempo-relative.

void time_listen	(	t_timeobject *	x,
		t_symbol *	attr,
		long	flags
	)

Specify that a millisecond-based attribute to be updated automatically when the converted milliseconds of the time object's value changes.

Parameters:

	x	The time object.
	attr	Name of the millisecond based attribute in the owning object that will be updated
	flags	If TIME_FLAGS_LISTENTICKS is passed here, updating will not happen if the time value is fixed (ms) based

void* time_new	(	t_object *	owner,
		t_symbol *	attrname,
		method	tick,
		long	flags
	)

Create a new time object.

Parameters:

	owner	Object that will own this time object (task routine, if any, will pass owner as argument).
	attrname	Name of the attribute associated with the time object.
	tick	Task routine that will be executed (can be NULL)
	flags	Options, see "Flags that determine time object behavior" above

Returns:

The newly created t_timeobject.

void time_now	(	t_timeobject *	x,
		t_timeobject *	quantize
	)

Schedule a task for right now, with optional quantization.

Parameters:

	x	The time object that schedules temporary events. The time interval is ignored and 0 ticks is used instead.
	quantize	A time object that holds a quantization interval, can be NULL for no quantization.

void time_schedule	(	t_timeobject *	x,
		t_timeobject *	quantize
	)

Schedule a task, with optional quantization.

Parameters:

	x	The time object that schedules temporary events (must have been created with TIME_FLAGS_USECLOCK but not TIME_FLAGS_PERMANENT)
	quantize	A time object that holds a quantization interval, can be NULL for no quantization.

void time_schedule_limit	(	t_timeobject *	x,
		t_timeobject *	quantize
	)

Schedule a task, with optional minimum interval,.

Parameters:

	x	The time object that schedules temporary events (must have been created with TIME_FLAGS_USECLOCK but not TIME_FLAGS_PERMANENT)
	quantize	The minimum interval into the future when the event can occur, can be NULL if there is no minimum interval.

void time_setclock	(	t_timeobject *	tx,
		t_symbol *	sc
	)

Associate a named setclock object with a time object (unsupported).

Parameters:

	tx	Time object.
	sc	Name of an associated setclock object.

void time_setvalue	(	t_timeobject *	tx,
		t_symbol *	s,
		long	argc,
		t_atom *	argv
	)

Set the current value of a time object (either an interval or a position) using a Max message.

Parameters:

	tx	The time object.
	s	Message selector.
	argc	Count of arguments.
	argv	Message arguments.

void time_stop

(

t_timeobject *

x

)

Stop a currently scheduled time object.

Parameters:

x

The time object.

void time_tick

(

t_timeobject *

x

)

Execute a time object's task, then if it was already set to execute, reschedule for the current interval value of the object.

Parameters:

x

The time object.

---

Variable Documentation

BEGIN_USING_C_LINKAGE typedef t_object t_itm

A low-level object for tempo-based scheduling.

See also:

t_timeobject

ITM

Definition at line 13 of file ext_itm.h.

BEGIN_USING_C_LINKAGE typedef t_object t_timeobject

A high-level time object for tempo-based scheduling.

See also:

t_itm

ITM

Definition at line 24 of file ext_time.h.