Max API

7.1.0

Generated by Doxygen 1.8.10

Tue Dec 15 2015 09:20:55

Chapter 1

Objects in C: A Roadmap

Max has an extensive API for developing new objects in C.Before you start learning about it, however, we would like
to save you time and make sure you learn the minimum about the API for what you need to do. Therefore, we've
made a brief list of application areas for object development along with the sections of this document with which
you'll probably want to become familiar.

1.1 Max Objects

For logic and arithmetic objects, such as new mathematical functions or more complex conditional operations
than what is offered in Max, it should be sufficient to read the Anatomy of a Max Object section.
For objects that use Data Structures, you'll want to read, in addition, the Atoms and Messages section to learn about
Max's basic mechanisms for representing and communicating data.
If you are interested in writing interfaces to operating system services, you may need to learn about Max's Thread-
ing model and The Scheduler.
For objects that deal with time and timing you'll want to learn about The Scheduler. If you're interested in tempo-
based scheduling, you'll want to read the section on ITM and look at the delay2 example.
To create new user interface gadgets, you'll want to read all of the above, plus the section on Attributes and the
Anatomy of a UI Object. The section on JGraphics will also be helpful.
To create objects with editing windows, things are much more complicated than they used to be. You'll need to
learn everything about UI objects, plus understand the scripto example object project.
For patcher scripting and interrogation objects, the section on Scripting the Patcher, plus a few of the examples will
be very helpful. It is also helpful to have a clear conceptual understanding of the patcher, which might be aided by
reading the patcher scripting sections of the js object documentation.
Max 6 introduced support for passing structured data with the Dictionary Passing API.

1.2 MSP Objects

To create audio filters and signal generators, read the Anatomy of a Max Object, then read the Anatomy of a
MSP Object section. MSP objects make use of Creating and Using Proxies when receiving multiple audio inputs,
so familiarity with that concept could be helpful.
For audio objects that output events (messages), you'll need to use the services of The Scheduler, so we suggest
reading about that.
For UI objects for analyzing and controlling audio, you'll need to learn about regular MSP objects as well as Max UI
objects.
Information on updating MSP objects from Max 5 or earlier for 64-bit audio (introduced in Max 6) is located in
2 Objects in C: A Roadmap

Appendix: Updating Externals for Max 6.

1.3 Jitter Objects

The Jitter Object Model outlines some important basic information about Jitter's flexible object model. Jitter Max
Wrappers describes how to write Max wrapper objects that contain Jitter objects for use in the Max patcher world.
Matrix Operator QuickStart and Matrix Operator Details describe how to create a particular type of Jitter object
called matrix operators, or MOPs. OB3D QuickStart and OB3D Details describe how to create OB3D Jitter objects
for use in rendering OpenGL scenes. Scheduler and Low Priority Queue Issues covers important threading and
timing issues when building Jitter objects. Jitter Object Registration and Notification explains how Jitter objects
can be registered by name and notify clients as they change or important events occur. Using Jitter Objects in
C provides some examples of how to instantiate and take advantage of Jitter objects from C, just as one would
from Java, Javascript, or the patcher. Finally, The JXF File Specification and Jitter Networking Specification contain
information relating to the data formats involved in the JXF file format and Jitter networking protocols, respectively.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 2

Development System Information

2.1 Building

This SDK documentation is accompanied by a series of projects for compiling some example Max external objects.
The details of how to build these projects are documented below in separate sections for the Mac and Windows.
When you build the example projects, the resulting Max external will be located in a folder called "externals" at the
top level of the SDK package. This is located a couple of folders up from the project and source file.
Place the SDK package in your "Packages" folder in order to load and test the externals you build in Max itself.

2.2 Build Script

We have provided a basic script that will build all of the projects in the SDK at once. This script is written using the
Ruby language. A Ruby interpretter is standard on the Mac. On windows you can download and install Ruby (1.9.3
recommended) from http://rubyinstaller.org/ .
Run from Terminal.app (Mac) or a Command Prompt (Windows) by cd'ing into the examples directory, and then
running:

ruby build.rb

2.3 Mac

Max external objects for the Mac are Mach-O bundles (folders that appear to be files) whose filenames must end
with the .mxo extension. The example projects have been tested using Xcode 6.2. Xcode is available through the
Apple Mac Store.
After installing Xcode, if you wish to run the aforementioned Ruby script, you will also need to install the Command
Line Tools. This is done via the menu item: Xcode > Open Developer Tool > More Development Tools...

2.3.1 XCode Project Setup

The example projects are set up to have Development and Deployment build configurations. The Development
configuration does not optimize and ensures debugging symbols are present. The Deployment configuration creates
a universal binary and performs optimization.
The files required for the projects are included in the project folders with the exception of the following two files:

• Info.plist
4 Development System Information

• maxmspsdk.xcconfig

These two files are located one folder-level up from the project folder, and are required for the Xcode project to build
the Max external.

2.3.2 Linking and Frameworks

External objects use dynamic linking to access the API functions provided by the Max application. When an object
is loaded, calls to functions inside the application are resolved by the operating system to the correct memory
address. Due to the fact that "Max" could exist as an application, a standalone you create, or a library inside
another application, an object's Xcode project does not link directly to a framework, library, or application. Instead,
the list of permitted symbols is provided to the linker. This list is defined in the aforementioned maxmspsdk.xcconfig
file.
Audio objects will link against MaxAudioAPI.framework and Jitter objects link against JitterAPI.framework. Alterna-
tively, you could also provide linker flags as we have provided for Max itself. The most recent version of all frame-
works will be found inside the application you are using (they are found inside the application bundle in Contents/←-
Frameworks). In addition, there are versions inside the c74support folder provided with the SDK. These will be used
only to link your objects; they are never actually executed.
Xcode uses something called the Frameworks Search Path to locate frameworks when linking. The example SDK
projects use a frameworks search path with a c74support folder two levels up from your the folder containing your
Xcode project. If you rearrange the SDK folders, projects may not find the frameworks and will fail to link properly.
Furthermore, even though we specify the frameworks search path, Xcode seems to look in /Library/Frameworks
first. If you have installed a version of the Max SDK for version 4.6 or ealier, you may have older versions of
MaxAPI.framework and MaxAudioAPI.framework in /Library/Frameworks. When you try to link objects that contain
references to functions only defined in the newest MaxAPI.framework, the link may fail because the projects are
using the old frameworks. To fix this, you'll need to remove the Max frameworks from /Library/Frameworks. If you
want to develop objects for both the Max 4.6 and Max 5 SDKs on the same machine, you'll need to modify your 4.6
projects to specify a Frameworks Search Path, and relocate the 4.6 frameworks to the specified location.

2.4 Windows

Max external objects for Windows are Dynamic Link Libraries (DLLs) whose filenames must end with the .mxe
extension (for 32-bit builds) or .mxe64 (for 64-bit builds). These DLLs will export a single function called "ext_←-
main" which is called by max when the external object is first loaded. Generally these DLLs will import functions of
the Max API from the import library "MaxAPI.lib" which is located in the c74support\max-includes\ folder. External
objects that use audio functionality will import functions from the import library "MaxAudio.lib" which is located in
c74support\msp-includes\. External objects that use Jitter functionality will import functions from the import library
"jitlib.lib" which is located in c74support\jit-includes\.

2.4.1 Compiling with Visual Studio

The example projects are in Visual C++ 2013 format (vcxproj files). A free version of Visual C++ can be obtained
from Microsoft at http://www.microsoft.com/express/. You will want to choose "Visual Studio Express
2013 for Windows Desktop".
The projects are set up to have both a Debug and a Release configuration. The Release configuration is optimized
whereas the Debug one is not. Note that for debugging purposes you can exercise your object in the Max Runtime
since the copy protection for the Max Application will interfere when run under the debugger.
Another thing to note is that Max has a private build of the Microsoft C Runtime Library for historical and backward
compatibility reasons. It is recommended that you link with Microsoft's standard C runtime library rather than the
Max C runtime library. When you include "ext.h" from the max API it will include ext_prefix.h which for the release
build will automatically cause your project to use the max C runtime library. To use the Microsoft C Runtime define
the C preprocessor macro MAXAPI_USE_MSCRT before including ext.h.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

2.5 Important Project Settings 5

2.5 Important Project Settings

The easiest way to create a new external is to choose one of the existing SDK examples, duplicate it, and then
change only the settings that need to be changes (such as the name of the project). This will help to guarantee that
important project settings are correct. Project settings of particular importance are noted below.

2.5.1 Mac

Particularly important for Max externals on the Mac are that the Info.plist is correct set up and that the "Force
Package Info Generation" is set to true. Without these your object may fail to load on some machines.

2.5.2 Windows

In the preprocessor definitions for the Visual Studio project it is important to define WIN_VERSION and EXT_WI←-
N_VERSION to ensure that the headers are set up properly.

2.6 Platform-specificity

If you are writing a cross-platform object and you need to do something that is specific to one platform, the Max API
headers provide some predefined symbols you can use.

#ifdef MAC_VERSION
// do something specific to the Mac
#endif
#ifdef WIN_VERSION
// do something specific to Windows
#endif

Another reason for conditional compilation is to handle endianness on the Mac platform. If you are still supporting
PowerPC, you may have situations where the ordering of bytes within a 16- or 32-bit word is important. ext_←-
byteorder.h provides cross-platform tools for manipulating memory in an endian-independent way.

2.7 Configuration

As the Max API evolves, the use of a number of older legacy functions are discouraged. Use of said functions will
issue a 'deprecation' warning when you try to compile the code. To disable these deprecation warnings you can
define the preprocessor symbol C74_NO_DEPRECATION in the target preprocessor section of your IDE.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

6 Development System Information

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 3

Anatomy of a Max Object

Max objects are written in the C language, and the Max API is C-based.
You could use C++ but we don't support it at the API level. Writing a Max object in C, you have five basic tasks:
1) including the right header files (usually ext.h and ext_obex.h)
2) declaring a C structure for your object
3) writing an initialization routine called ext_main that defines the class
4) writing a new instance routine that creates a new instance of the class, when someone makes one or types its
name into an object box
5) writing methods (or message handlers) that implement the behavior of the object
Let's look at each of these in more detail. It's useful to open the simplemax example project as we will be citing
examples from it.

3.1 Include Files

Most of the basic Max API is included in the files ext.h and ext_obex.h. These are essentially required for any object.
Beyond this there are specific include files for more specialized objects.
The header files are cross-platform.

• jpatcher_api.h is required for any Max UI objects

• z_dsp.h is required for MSP audio objects

#include "ext.h" // should always be first, followed by ext_obex.h and any other files.

3.2 The Object Declaration

Basic Max objects are declared as C structures. The first element of the structure is a t_object, followed by whatever
you want. The example below has one long structure member.

typedef struct _simp

{
t_object s_obj; // t_object header
long s_value; // something else
} t_simp;

Your structure declaration will be used in the prototypes to functions you declare, so you'll need to place above these
prototypes.
8 Anatomy of a Max Object

3.3 Initialization Routine

The initialization routine, which must be called ext_main, is called when Max loads your object for the first time. In
the initialization routine, you define one or more classes. Defining a class consists of the following:
1) telling Max about the size of your object's structure and how to create and destroy an instance 2) defining
methods that implement the object's behavior 3) in some cases, defining attributes that describe the object's data
4) registering the class in a name space
Here is the simp class example initialization routine:

static t_class *s_simp_class; // global pointer to our class definition that is setup in ext_main()

void ext_main(void *r)

{
t_class *c;

c = class_new("simp", (method)simp_new, (method)NULL, sizeof(t_simp), 0L, 0);

class_addmethod(c, (method)simp_int, "int", A_LONG, 0);
class_addmethod(c, (method)simp_bang, "bang", 0);

class_register(CLASS_BOX, c);

s_simp_class = c;
}

In order for Max to call the ext_main() function on your compiled external, that function must be "exported" or made
public. This is accomplished by using the C74_EXPORT macro in the prototype of the ext_main() function, which is
provided for you automatically in the "ext.h" header file.
class_new() creates a class with the new instance routine (see below), a free function (in this case there isn't one,
so we pass NULL), the size of the structure, a no-longer used argument, and then a description of the arguments
you type when creating an instance (in this case, there are no arguments, so we pass 0).
class_addmethod() binds a C function to a text symbol. The two methods defined here are int and bang.
class_register() adds this class to the CLASS_BOX name space, meaning that it will be searched when a user tries
to type it into a box.
Finally, we assign the class we've created to a global variable so we can use it when creating new instances.
More complex classes will declare more methods. In many cases, you'll declare methods to implement certain API
features. This is particularly true for UI objects.

3.4 New Instance Routine

The standard new instance routine allocates the memory to create an instance of your class and then initializes this
instance. It then returns a pointer to the newly created object.
Here is the simp new instance routine

void *simp_new()
{
t_simp *x = (t_simp *)object_alloc(s_simp_class);

x->s_value = 0;

return x;
}

The first line uses the global variable s_simp_class we defined in the initialization routine to create a new instance
of the class. Essentially, the instance is a block of memory of the size defined by the class, along with a pointer to
the class that permits us to dispatch messages correctly.
The next line initializes our data. More complex objects will do a lot more here, such as creating inlets and outlets.
By default, the object being created will appear with one inlet and no outlets.
Finally, in the last line, we return a pointer to the newly created instance.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

3.5 Message Handlers 9

3.5 Message Handlers

We are now ready to define some actual behavior for our object by writing C functions that will be called when our
object is sent messages. For this simple example, we will write only two functions. simp_int will be called when our
object receives numbers. It will store the received number in the s_value field. simp_bang will be called when our
object receives a bang. It will print the value in the Max window. So, yes, this object is pretty useless!
The C functions you write will be declared according to the arguments the message requires. All functions are
passed a pointer to your object as the first argument. For a function handling the int message, a single second
argument that is a long is passed. For a function handling the bang message, no additional arguments are passed.
Here is the int method:

void simp_int(t_simp *x, long n)

{
x->s_value = n;
}

This simply copies the value of the argument to the internal storage within the instance.
Here is the bang method:

void simp_bang(t_simp *x)

{
post("value is %ld",x->s_value);
}

The post() function is similar to printf(), but puts the text in the Max window. post() is very helpful for debugging,
particularly when you cannot stop user interaction or real-time computation to look at something in a debugger.
You can also add a float message, which is invoked when a floating-point number is sent to your object. Add the
following to your initialization routine:

class_addmethod(c, (method)simp_float, "float", A_FLOAT, 0);

Then write the method that receives the floating-point value as follows:

void simp_float(t_simp *x, double f)

{
post("got a float and it is %.2f", f);
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

10 Anatomy of a Max Object

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 4

Inlets and Outlets

You are familiar with inlets and outlets when connecting two objects together in a patcher.
To receive data in your object or send data to other objects, you need to create the C versions of inlets and outlets.
In this section, we'll explain what inlets and outlets are, how to create them, and how to use them. We'll also discuss
a more advanced type of inlet called a proxy that permits a message to be received in any of your object's inlets.
Proxies are used by audio objects to permit inlets to handle both signals and normal Max messages.
By default, every object shows one inlet. Additional inlets appear to the right of the default inlet, with the rightmost
inlet being created last.
Inlets are essentially message translators. For example, if you create an int inlet, your object will receive the "in1"
message instead of the "int" message when a number arrives at this newly created inlet. You can use the different
message name to define special behavior for numbers arriving at each inlet. For example, a basic arithmetic object
in Max such as + stores the number to be added when it arrives in the right inlet, but performs the computation and
outputs the result when a number arrives in the left inlet.
Outlets define connections between objects and are used to send messages from your object to the objects to
which it is connected. What is not obvious about an outlet, however, is that when you send a number out an outlet,
the outlet-sending function does not return until all computation "below" the outlet has completed. This stack-based
execution model is best illustrated by observing a patch with the Max debugger window. To understand this stack-
based model it may be helpful to use the breakpoint and debugging features in Max and follow the stack display as
you step through the execution of a patch. Outlets, like inlets, appear in the order you create them from right-to-left.
In other words, the first inlet or outlet you create will be the visually farthest to the right.

4.1 Creating and Using Inlets

Proper use of an inlet involves two steps: first, add a method that will respond to the message sent via the inlet
in your initialization routine, and second, create the inlet in your new instance routine. (Creating inlets at any other
time is not supported.)
There are three types of inlets: int, float, and custom. We'll only describe int and float inlets here because proxies
are generally a better way to create an inlet that can respond to any message. For int inlets, you'll bind a function
to a message "in1", "in2", "in3" etc. depending on the inlet number you assign. Here's how to create a single inlet
using "in1"...
In your initialization routine:

class_addmethod(c, (method)myobject_in1, "in1", A_LONG, 0);

In your new instance routine, after calling object_alloc() to create your instance:

intin(x, 1);

The method that will be called when an int is received in the right inlet:
12 Inlets and Outlets

void myobject_in1(t_myobject *x, long n)

{
// do something with n
}

Creating a single inlet in this way gives your object two inlets (remember that it always has one by default). If you
want to create multiple inlets, you'll need to create them in order from right to left, as shown below:

intin(x, 2); // creates an inlet (the right inlet) that will send your object the "in2" message
intin(x, 1); // creates an inlet (the middle inlet) that will send your object the "in1" message

Inlets that send float messages to your object are created with floatin() and translate the float message into
"ft1","ft2","ft3" etc. Example:
In initialization routine:

class_addmethod(c, (method)myobject_ft1, "ft1", A_FLOAT, 0);

In new instance routine:

floatin(x, 1);

Method:

void myobject_ft1(t_myobject *x, double f)

{
post("float %.2f received in right inlet,f);
}

Note that you can mix int and float inlets, but each inlet must have a unique number. Example:

intin(x, 2);
floatin(x, 1);

4.2 Creating and Using Outlets

You create outlets in your new instance routine. Outlet creators return a pointer that you should store for later use
when you want to send a message. As with inlets, outlets are created from right to left.
Here's a simple example. First we'll add two void pointers to our data structure to store the outlets for each instance.

typedef struct _myobject

{
t_object m_ob;
void *m_outlet1;
void *m_outlet2;
} t_myobject;

Then we'll create the outlets in our new instance routine.

x = (t_myobject *)object_alloc(s_myobject_class);
x->m_outlet2 = bangout((t_object *)x);
x->m_outlet1 = intout((t_object *)x);
return x;

These outlets are type-specific, meaning that we will always send the same type of message through them. If you
want to create outlets that can send any message, use outlet_new(). Type-specific outlets execute faster, because
they make a direct connection to the method handler that will be called at the time you send a message. When we
want to send messages out these outlets, say, in our bang method, we do the following:

void myobject_bang(t_myobject *x)

{
outlet_bang(x->m_outlet2);
outlet_int(x->m_outlet1, 74);
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

4.3 Creating and Using Proxies 13

The bang method above sends the bang message out the m_outlet2 outlet first, then sends the number 74 out the
m_outlet1. This is consistent with the general design in Max to send values out outlets from right to left. However,
there is nothing enforcing this design, and you could reverse the statements if you felt like it.
A more general message-sending routine, outlet_anything(), will be shown in the Atoms and Messages section.

4.3 Creating and Using Proxies

A proxy is a small object that controls an inlet, but does not translate the message it receives. Instead it sets a
location inside your object's data structure to a value you associate with the inlet. If the message comes "directly" to
your object via the left inlet, the value will be 0. However, in order to be thread-safe, you should not read the value
of this "inlet number" directly. Instead, you'll use the proxy_getinlet() routine to determine the inlet that has received
the message.
The advantage of proxies over regular inlets is that your object can respond to any message in all of its inlets, not
just the left inlet. As a Max user, you may already appreciate the proxy feature without knowing it. For example, the
pack object can combine ints, floats, lists, or symbols arriving in any of its inlets. It uses proxies to make this happen.
MSP audio objects that accept signals in more than one inlet use proxies as well. In fact, the proxy capability is built
into the way you create audio objects, as will be discussed in the Anatomy of a MSP Object section.
If your object's non-left inlets will only respond to ints or floats, implementing proxies is usually overkill.

4.4 Example

First, add a place in your object to store the proxy value. You shouldn't access this directly, but the proxy needs it.
Second, you'll need to store the proxy, because you need to free it when your object goes away. If you create many
proxies, you'll need to store pointers to all of them, but all proxies share the same long integer value field.

typedef struct _myobject

{
t_object m_obj;
long m_in; // space for the inlet number used by all the proxies
void *m_proxy;
} t_myobject;

In your new instance routine, create the proxy, passing your object, a non-zero code value associated with the proxy,
and a pointer to your object's inlet number location.

x->m_proxy = proxy_new((t_object *)x, 1, &x->m_in);

If you want to create regular inlets for your object, you can do so. Proxies and regular inlets can be mixed, although
such a design might confuse a user of your object.
Finally, here is a method that takes a different action depending on the value of x->m_in that we check using
proxy_getinlet().

void myobject_bang(t_myobject *x)

{
switch (proxy_getinlet((t_object *)x)) {
case 0:
post("bang received in left inlet");
break;
case 1:
post("bang received in right inlet");
break;
}
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

14 Inlets and Outlets

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 5

Atoms and Messages

When a Max object receives a message, it uses its class to look up the message selector ("int", "bang", "set" etc.)
and invoke the associated C function (method).
This association is what you are creating when you use class_addmethod() in the initialization routine. If the lookup
fails, you'll see an "object doesn't understand message" error in the Max window.
Message selectors are not character strings, but a special data structure called a symbol (t_symbol). A symbol
holds a string and a value, but what is more important is that every symbol in Max is unique. This permits you to
compare two symbols for equivalence by comparing pointers, rather than having to compare each character in two
strings.
The "data" or argument part of a message, if it exists, is transmitted in the form of an array of atoms (t_atom). The
atom is a structure that can hold integers, floats, symbols, or even pointers to other objects, identified by a tag. You'll
use symbols and atoms both in sending messages and receiving them.
To illustrate the use of symbols and atoms, here is how you would send a message out an outlet. Let's say we
want to send the message "green 43 crazy 8.34." This message consists of a selector "green" plus an array of three
atoms.
First, we'll need to create a generic outlet with outlet_new in our new instance routine.

x->m_outlet = outlet_new((t_object *)x, NULL);

The second argument being NULL indicates that the outlet can be used to send any message. If the second
argument had been a character string such as "int" or "set" only that specific message could be sent out the outlet.
You'd be correct if you wondered whether intout() is actually just outlet_new(x, "int").
Now that we have our generic outlet, we'll call outlet_anything() on it in a method. The first step, however, is to
assemble our message, with a selector "green" plus an array of atoms. Assigning ints and floats to an atom is
relatively simple, but to assign a symbol, we need to transform a character string into a symbol using gensym().
The gensym() function returns a pointer to a symbol that is guaranteed to be unique for the string you supply. This
means the string is compared with other symbols to ensure its uniqueness. If it already exists, gensym() will supply
a pointer to the symbol. Otherwise it will create a new one and store it in a table so it can be found the next time
someone asks for it.

void myobject_bang(t_object *x)

{
t_atom argv[3];

atom_setlong(argv, 43);
atom_setsym(argv + 1, gensym("crazy"));
atom_setfloat(argv + 2, 8.34);

outlet_anything(x->m_outlet, gensym("green"), 3, argv);

}

In the call to outlet_anything() above, gensym("green") represents the message selector. The outlet_anything()
function will try to find a message "green" in each of the objects connected to the outlet. If outlet_anything() finds
such a message, it will execute it, passing it the array of atoms it received.
16 Atoms and Messages

If it cannot find a match for the symbol green, it does one more thing, which allows objects to handle messages
generically. Your object can define a special method bound to the symbol "anything" that will be invoked if no
other match is found for a selector. We'll discuss the anything method in a moment, but first, we need to return to
class_addmethod() and explain the final arguments it accepts.
To access atoms, you can use the functions atom_setlong(), atom_getlong() etc. or you can access the t_atom
structure directly. We recommend using the accessor functions, as they lead to both cleaner code and will permit
your source to work without modifications when changes to the t_atom structure occur over time.

5.1 Argument Type Specifiers

In the simp example, you saw the int method defined as follows:

class_addmethod(c, (method)simp_int, "int", A_LONG, 0);

The A_LONG, 0 arguments to class_addmethod() specify the type of arguments expected by the C function you
have written. A_LONG means that the C function accepts a long integer argument. The 0 terminates the argument
specifier list, so for the int message, there is a single long integer argument.
The other options are A_FLOAT for doubles, A_SYM for symbols, and A_GIMME, which passes the raw list of
atoms that were originally used to send the Max message in the first place. These argument type specifiers define
what are known as "typed" methods in Max. Typed methods are those where Max checks the type of each atom in
a message to ensure it is consistent with what the receiving object has said it expects for a given selector.
If the atoms cannot be coerced into the format of the argument type specifier, a bad arguments error is printed in
the Max window.
There is a limit to the number of specifiers you can use, and in general, multiple A_FLOAT specifiers should be
avoided due to the historically unpredictable nature of compiler implementations when passing floating-point values
on the stack. Use A_GIMME for more than four arguments or with multiple floating-point arguments.
You can also specify that missing arguments to a message be filled in with default values before your C function
receives them. A_DEFLONG will put a 0 in place of a missing long argument, A_DEFFLOAT will put 0.0 in place
of a missing float argument, and A_DEFSYM will put the empty symbol (equal to gensym("")) in place of a missing
symbol argument.

5.2 Writing A_GIMME Functions

A method that uses A_GIMME is declared as follows:

void myobject_message(t_myobject *x, t_symbol *s, long argc, t_atom *argv);

The symbol argument s is the message selector. Ordinarily this might seem redundant, but it is useful for the
"anything" method as we'll discuss below.
argc is the number of atoms in the argv array. It could be 0 if the message was sent without arguments. argv is the
array of atoms holding the arguments.
For typed messages, the atoms will be of type A_SYM, A_FLOAT, or A_LONG. Here is an example of a method
that merely prints all of the arguments.

void myobject_printargs(t_myobject *x, t_symbol *s, long argc, t_atom *argv)

{
long i;
t_atom *ap;

post("message selector is %s",s->s_name);

post("there are %ld arguments",argc);

// increment ap each time to get to the next atom

for (i = 0, ap = argv; i < argc; i++, ap++) {
switch (atom_gettype(ap)) {

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

5.3 Writing "Anything" Methods 17

case A_LONG:
post("%ld: %ld",i+1,atom_getlong(ap));
break;
case A_FLOAT:
post("%ld: %.2f",i+1,atom_getfloat(ap));
break;
case A_SYM:
post("%ld: %s",i+1, atom_getsym(ap)->s_name);
break;
default:
post("%ld: unknown atom type (%ld)", i+1, atom_gettype(ap));
break;
}
}
}

You can interpret the arguments in whatever manner you wish. You cannot, however, modify the arguments as they
may be about to be passed to another object.

5.3 Writing "Anything" Methods

As previously mentioned, your object can define a special method bound to the symbol "anything" that will be
invoked if no other match is found for a selector. For example:

class_addmethod(c, (method)myobject_anything, "anything",

A_GIMME, 0);

Your function definition for an anything method follows the same pattern as for all other A_GIMME methods:

void myobject_anything(t_myobject *x, t_symbol *s, long argc, t_atom *argv)

{
object_post( (t_object*)x,
"This method was invoked by sending the ’%s’ message to this object.",
s->s_name);
// argc and argv are the arguments, as described in above.
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

18 Atoms and Messages

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 6

The Scheduler

The Max scheduler permits operations to be delayed until a later time.

It keeps track of time in double-precision, but the resolution of the scheduler depends on the user's environment
preferences. The scheduler also works in conjunction with a low-priority queue, which permits time-consuming
operations that might be initiated inside the scheduler to be executed in a way that does not disrupt timing accuracy.
Most objects interface with the scheduler via a clock (t_clock) object. A clock is associated with a task function that
will execute when the scheduler's current time reaches the clock's time. There is also a function called schedule()
that can be used for one-off delayed execution of a function. It creates a clock to do its job however, so if your object
is going to be using the scheduler repeatedly, it is more efficient to store references to the clocks it creates so the
clocks can be reused.
The scheduler is periodically polled to see if it needs to execute clock tasks. There are numerous preferences Max
users can set to determine when and how often this polling occurs. Briefly:

• The Overdrive setting determines whether scheduler polling occurs in a high-prority timer thread or the main
thread

• The Interval setting determines the number of milliseconds elapse between polling the scheduler

• The Throttle setting determines how many tasks can be executed in any particular scheduler poll

Similar Throttle and Interval settings exist for the low-priority queue as well.
For more information refer to the Timing documentation. While the details might be a little overwhelming on first
glance, the important point is that the exact time your scheduled task will execute is subject to variability. Max
permits this level of user control over the scheduler to balance all computational needs for a specific application.

6.1 Creating and Using Clocks

There are five steps to using a clock in an external object.

1. Add a member to your object's data structure to hold a pointer to the clock object

typedef struct _myobject

{
t_object m_obj;

void *m_clock;
} t_object;

2. Write a task function that will do something when the clock is executed. The function has only a single argument,
a pointer to your object. The example below gets the current scheduler time and prints it.

void myobject_task(t_myobject *x)

20 The Scheduler

{
double time;

sched_getftime(&time);
post("instance %lx is executing at time %.2f", x, time);
}

3. In your new instance routine, create the clock (passing a pointer to your object and the task function) and store
the result in your object's data structure.

x->m_clock = clock_new((t_object *)x, (method)myobject_task);

4. Schedule your clock. Use clock_fdelay() to schedule the clock in terms of a delay from the current time. Below
we schedule the clock to execute 100 milliseconds from now.

clock_fdelay(x->m_clock, 100.);

If you want to cancel the execution of a clock for some reason, you can use clock_unset().

clock_unset(x->m_clock);

5. In your object's free routine, free the clock

object_free(x->m_clock);

Note that if you call clock_delay() on a clock that is already set, its execution time will be changed. It won't execute
twice.

6.2 Creating and Using Qelems

A qelem ("queue element") is used to ensure that an operation occurs in the low-priority thread. The task function
associated with a t_qelem is executed when the low-priority queue is serviced, always in the main (user interface)
thread. Any qelem that is "set" belongs to the low-priority queue and will be executed as soon as it serviced.
There are two principal things you want to avoid in the high priority thread: first, time-consuming or unpredictable
operations such as file access, and second, anything that will block execution for any length of time – for example,
showing a dialog box (including a file dialog).
The procedure for using a qelem is analogous to that for using a clock.
1. Add a member to your object's data structure to hold a pointer to the qelem

typedef struct _myobject

{
t_object m_obj;

void *m_qelem
} t_myobject;

2. Write a task function that will do something when the qelem is executed. The function has only a single argument,
a pointer to your object.

void myobject_qtask(t_myobject *x)

{
post("I am being executed a low priority!"
}

3. In your new instance routine, create the qelem (passing a pointer to your object and the task function) and store
the result in your object's data structure.

x->m_qelem = qelem_new((t_object *)x, (method)myobject_qtask);

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

6.3 Defer 21

4. Set the qelem by using qelem_set(). You could, for example, call qelem_set() in a clock task function or in direct
response to a message such as bang or int.

qelem_set(x->m_qelem);

If you want to cancel the execution of a qelem for some reason, you can use qelem_unset().

qelem_unset(x->m_qelem);

5. In your object's free routine, call qelem_free(). Do not call object_free() or freeobject() – unlike the clock, the
qelem is not an object.

qelem_free(x->m_qelem);

Note that if you call qelem_set() on a qelem that is already set, it won't execute twice. This is a feature, not a bug,
as it permits you to execute a low-priority task only as fast as the low-priority queue operates, not at the high-priority
rate that the task might be triggered. An example would be that a number box will redraw more slowly than a counter
that changes its value. This is not something you need to worry about, even if you are writing UI objects, as Max
handles it internally (using a qelem).

6.3 Defer

The defer function and its variants use a qelem to ensure that a function executes at low-priority. There are three
variants: defer(), defer_low(), and defer_medium(). The difference between using defer() and a qelem is that defer()
is a one-shot deal – it creates a qelem, sets it, and then gets rid of it when the task function has executed. The
effect of this is that if you have some rapid high-priority event that needs to trigger something to happen at low-
priority, defer() will ensure that this low-priority task happens every time the high-priority event occurs (in a 1:1
ratio), whereas using a qelem will only run the task at a rate that corresponds to the service interval of the low-
priority queue. If you repeatedly defer() something too rapidly, the low-priority queue will become backlogged and
the responsiveness of the UI will suffer.
A typical use of defer() is if your object implements a read message to ask the user for a file. Opening the dialog in
the timer thread and waiting for user input will likely crash, but even if it didn't, the scheduler would effectively stop.
To use defer(), you write a deferred task function that will execute at low priority. The function will be passed a
pointer to your object, plus a symbol and atom list modeled on the prototype for an anything method. You need not
pass any arguments to the deferred task if you don't need them, however.

void myobject_deferredtask(t_myobject *x, t_symbol *s, long argc, t_atom *argv)

{
post("I am deferred");
}

To call the task, use defer() as shown below. The first example passes no arguments. The second passes a couple
of long atoms.

defer((t_object *)x, (method)myobject_deferredtask, NULL, 0, NULL);

t_atom av[2];

atom_setlong(av, 1);
atom_setlong(av+ 2, 74);

defer((t_object *)x, (method)myobject_deferredtask, NULL, 2, av);

Defer copies any atoms you pass to newly allocated memory, which it frees when the deferred task has executed.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

22 The Scheduler

6.3.1 Defer Variants

defer has two variants, defer_low() and defer_medium(). Here is a comparison:

defer()
If executing at high priority, defer() puts the deferred task at the front of the low-priority queue. If not executing at
highpriority, defer() calls the deferred task immediately.
defer_low()
At all priority levels, defer_low() puts the deferred task at the back of the low-priority queue.
defer_medium()
If executing at high priority, defer_medium() puts the deferred task at the back of the low-priority queue. If not
executing at high priority, defer_medium() calls the deferred task immediately.

6.4 Schedule

The schedule() function is to clocks as defer() is to qelems. Schedule creates a clock for a task function you specify
and calls clock_fdelay() on it to make the task execute at a desired time. As with defer(), schedule() can copy
arguments to be delivered to the task when it executes.
A schedule() variant, schedule_defer(), executes the task function at low priority after a specified delay.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 7

Memory Allocation

The Max API offers cross-platform calls memory management.

There are two types of calls, those for pointers and those for handles. Handles are pointers to pointers, and were
used in the early Mac OS to permit memory to be relocated without changing a reference, and many Mac OS API
calls used handle. There are a few legacy Max API calls that use handles as well, but in general, unless the OS or
Max requires the use of a handle, you're probably better off using the simpler pointer.
Longtime Max object programmers may have used memory calls getbytes() and freebytes() in the past, but all mem-
ory calls now use same underlying OS mechanisms, so while getbytes() and freebytes() are still supported, they are
restricted to 32K of memory or less due to the arguments they use, and we recommend the use of sysmem_newptr()
and sysmem_freeptr() instead.
Here are some examples of allocating and freeing pointers and handles.

char *ptr;
char **hand;

ptr = sysmem_newptr(2000);
post("I have a pointer %lx and it is %ld bytes in size",ptr, sysmem_ptrsize(ptr));
ptr = sysmem_resizeptrclear(ptr, 3000);
post("Now I have a pointer %lx and it is %ld bytes in size",ptr,
sysmem_ptrsize(ptr));
sysmem_freeptr(ptr);

hand = sysmem_newhandle(2000);
post("I have a handle %lx and it is %ld bytes in size",hand,
sysmem_handlesize(hand));
sysmem_resizehandle(hand, 3000);
post("Now the handle %lx is %ld bytes in size",hand, sysmem_ptrsize(hand));
sysmem_freehandle(hand);
24 Memory Allocation

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 8

Anatomy of a MSP Object

An MSP object that handles audio signals is a regular Max object with a few extras.
Refer to the simplemsp∼ example project source as we detail these additions. simplemsp∼ is simply an object that
adds a number to a signal, identical in function to the regular MSP +∼ object if you were to give it an argument of 1.
Here is an enumeration of the basic tasks:

8.1 Additional Header Files

After including ext.h and ext_obex.h, include z_dsp.h

#include "z_dsp.h"

8.2 C Structure Declaration

The C structure declaration must begin with a t_pxobject, not a t_object:

typedef struct _mydspobject

{
t_pxobject m_obj;
// rest of the structure’s fields
} t_mydspobject;

8.3 Initialization Routine

When creating the class with class_new(), you must have a free function. If you have nothing special to do, use
dsp_free(), which is defined for this purpose. If you write your own free function, the first thing it should do is call
dsp_free(). This is essential to avoid crashes when freeing your object when audio processing is turned on.

c = class_new("mydspobject", (method)mydspobject_new, (method)dsp_free, sizeof(

t_mydspobject), NULL, 0);

After creating your class with class_new(), you must call class_dspinit(), which will add some standard method
handlers for internal messages used by all signal objects.

class_dspinit(c);

Your signal object needs a method that is bound to the symbol "dsp" – we'll detail what this method does below, but
the following line needs to be added while initializing the class:

class_addmethod(c, (method)mydspobject_dsp64, "dsp64",

A_CANT, 0);
26 Anatomy of a MSP Object

8.4 New Instance Routine

The new instance routine must call dsp_setup(), passing a pointer to the newly allocated object pointer plus a
number of signal inlets the object will have. If the object has no signal inlets, you may pass 0. The simplemsp∼
object (as an example) has a single signal inlet:

dsp_setup((t_pxobject *)x, 1);

dsp_setup() will make the signal inlets (as proxies) so you need not make them yourself.
If your object will have audio signal outputs, they need to be created in the new instance routine with outlet_new().
However, you will never access them directly, so you don't need to store pointers to them as you do with regular
outlets. Here is an example of creating two signal outlets:

outlet_new((t_object *)x, "signal");

outlet_new((t_object *)x, "signal");

8.5 The DSP Method and Perform Routine

The dsp64 method specifies the signal processing function your object defines along with its arguments. Your
object's dsp64 method will be called when the MSP signal compiler is building a sequence of operations (known as
the DSP Chain) that will be performed on each set of audio samples. The operation sequence consists of a pointers
to functions (called perform routines) followed by arguments to those functions.
The dsp64 method is declared as follows:

void mydspobject_dsp64(t_mydspobject *x, t_object *dsp64, short *count, double samplerate, long
maxvectorsize, long flags);

To add an entry to the DSP chain, your dsp64 method uses the "dsp_add64" method of the DSP chain. The dsp←-
_add64 method is passed an a pointer to your object, a pointer to a perform64 routine that calculates the samples,
an optional flag which may alter behavior, and a generic pointer which will be passed on to your perform routine.

object_method(dsp64, gensym("dsp_add64"), x, mydspobject_perform64, 0, NULL);

The perform routine is not a "method" in the traditional sense. It will be called within the callback of an audio driver,
which, unless the user is employing the Non-Real Time audio driver, will typically be in a high-priority thread. Thread
protection inside the perform routine is minimal. You can use a clock, but you cannot use qelems or outlets.
Here is a perform routine that adds a constant of 1 to any incoming signal:

void mydspobject_perform64(t_mydspobject *x, t_object *dsp64, double **ins, long numins, double **
outs, long numouts, long sampleframes, long flags, void *userparam)
{
double *in = ins[0]; // first inlet
double *out = outs[0]; // first outlet
int n = sampleframes; // vector size
t_double value;

while (n--) { // perform calculation on all samples

value = *in++;
*out++ = value + 1.0;
}
}

8.6 Free Function

The free function for the class must either be dsp_free() or it must be written to call dsp_free() as shown in the
example below:

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

8.6 Free Function 27

void mydspobject_free(t_mydspobject *x)

{
dsp_free((t_pxobject *)x);

// can do other stuff here

}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

28 Anatomy of a MSP Object

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 9

Advanced Signal Object Topics

Here are some techniques for implementing additional features found in most signal objects.

9.1 Saving Internal State

To implement unit generators such as filters and ramp generators, you need to save internal state between calls to
your object's perform routine. Here is a very simple low-pass filter (it just averages successive samples) that saves
the value of the last sample in a vector to be averaged with the first sample of the next vector. First we add a field
to our data structure to hold the value:

typedef struct _myfilter

{
t_pxobject f_obj;
double f_sample;
} t_myfilter;

Then, in our dsp method, we pass a pointer to the object as one of the DSP chain arguments. The dsp method also
initializes the value of the internal state, to avoid any noise when the audio starts.

void myfilter_dsp64(t_myfilter *x, t_object *dsp64, short *count, double samplerate, long
maxvectorsize, long flags)
{
object_method(dsp64, gensym("dsp_add64"), x, myfilter_perform64, 0, NULL);
x->f_sample = 0.0;
}

Here is the perform routine, which obtains the internal state before entering the processing loop, then stores the
most recent value after the loop is finished.

void myfilter_perform64(t_myfilter *x, t_object *dsp64, double **ins, long numins, double **outs,
long numouts, long sampleframes, long flags, void *userparam)
{
double *in = ins[0]; // first inlet
double *out = outs[0]; // first outlet
int n = sampleframes; // vector size
double samp = x->f_sample; // read from internal state
double val;

while (n--) {
val = *in++;
*out++ = (val + samp) * 0.5;
samp = val;
}
x->f_sample = samp; // save to internal state
}
30 Advanced Signal Object Topics

9.2 Using Connection Information

The third argument to the dsp method is an array of numbers that enumerate the number of objects connected to
each of your objects inputs and outputs. More advanced dsp methods can use this information for optimization
purposes. For example, if you find that your object has no inputs or outputs, you could avoid calling 'dsp_add64'
altogether. The MSP signal operator objects (such as +∼ and ∗∼) use this to implement a basic polymorphism:
they look at the connections count to determine whether the perform routine should use scalar or signal inputs. For
example, if the right input has no connected signals, the user can add a scalar value sent to the right inlet.
To implement this behavior, you have a few different options. The first option is to write two different perform
methods, one which handles the two-signal case, and one which handles the scalar case. The dsp method looks at
the count array and passes a different function to dsp_add64.

if (count[1]) // signal connected to second inlet

object_method(dsp64, gensym("dsp_add64"), x, mydspobject_twosigperform64, 0, NULL);
else
object_method(dsp64, gensym("dsp_add64"), x, mydspobject_scalarperform64, 0, NULL);

The second option is to store the value of the count array for a particular signal in your object's struct. Then the
perform method can make the decision whether to use the signal value or a scalar value that has been stored by
the object. In this case, many objects use a single sample value from the signal as a substitute for the scalar. Using
the first sample (i.e., the value at index 0) is a technique that works for any vector size, since vector sizes could be
as small as a single sample. Here is an example of this technique for an object that has two inputs and one output.
The connection count for the right input signal is stored in a struct member named m_count:

x->m_count = count[1];
object_method(dsp64, gensym("dsp_add64"), x, mydspobject_perform64, 0, NULL);

Here is a perform routine that uses the connection count information as passed in the format shown above:

void mydspobject_perform64(t_mydspobject *x, t_object *dsp64, double **ins, long numins, double **
outs, long numouts, long sampleframes, long flags, void *userparam)
{
t_mydspobject *x = (t_mydspobject *)w[1];
int connected = x->m_count;
double *in = ins[0];
double *in2 = ins[1];
double *out = outs[0];
int n = sampleframes;
double in2value;

// get scalar sample or use signal depending on whether signal is connected

in2value = connected ? *in2 : x->m_scalarvalue;

// do calculation here
// ...
}

9.3 Working with Buffer Objects

To access a named buffer∼ object for either reading or writing sample values, refer to the Buffers reference.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 10

Sending Messages, Calling Methods

Max objects, such as the one you write, are C data structures in which methods are dynamically bound to functions.
Your object's methods are called by Max, but your object can also call methods itself. When you call a method, it is
essential to know whether the method you are calling is typed or not.
Calling a typed method requires passing arguments as an array of atoms. Calling an untyped method requires that
you know the exact arguments of the C function implementing the method. In both cases, you supply a symbol that
names the method.
In the typed method case, Max will take the array of atoms and pass the arguments to the object according to the
method's argument type specifier list. For example, if the method is declared to have an argument type specifier
list of A_LONG, 0, the first atom in the array you pass will be converted to an int and passed to the function on
the stack. If there are no arguments supplied, invoking a typed method that has A_LONG, 0 as an argument type
specifier will fail. To make typed method calls, use object_method_typed() or typedmess().
In the untyped method case, Max merely does a lookup of the symbol in the object, and, if a matching function is
found, calls the function with the arguments you pass.
Certain methods you write for your object, such as the assist method for describing your object and the DSP method
in audio objects, are declared as untyped using the A_CANT argument type specifier. This means that Max will not
typecheck the arguments you pass to these methods, but, most importantly, a user cannot hook up a message box
to your object and send it a message to invoke an untyped method. (Try this for yourself – send the assist message
to a standard Max object.)
When you use an outlet, you're effectively making a typed method call on any objects connected to the outlet.

10.1 Attributes

Attributes are descriptions of data in your object. The standardization of these descriptions permits Max to provide
a rich interface to object data, including the pattr system, inspectors, the quick reference menu, @ arguments, etc.
It is essential that you have some understanding of attributes if you are going to write a UI object. But non-UI objects
can make use of attributes as well. The discussion below is not specific to UI objects. It does however, use the
recently introduced system of macros in ext_obex_util.h (included in ext_obex.h) for defining attributes, as well as
describing them using attributes of attributes (attr attrs). You can read more detailed descriptions of the underlying
attribute definition mechanisms on a per-function basis in the Attributes reference.

10.1.1 Attribute Basics

While attributes can be defined for a specific instance of an object, it's much more common to define an attribute for
a class. In such a case, each instance of the class will have the attribute description, but the value will be instance
specific. The discussion here focuses only on class attributes.
When an attribute is declared and is made user-settable, a user can send a message to your object consisting of the
32 Sending Messages, Calling Methods

attribute name and arguments that represent the new value of the attribute. For example, if you declare an attribute
called trackcount, the message trackcount 20 will set it to 20. You don't need to do anything special to obtain this
behavior. In addition, user-settable attributes will appear when the user opens the inspector on your object.
If you define your attribute as an offset attribute, you describe its location (and size) within your object's C data
structure. Max can then read and write the data directly. You can also define custom getter and setter routines
if the attribute's value is more complex than simply a stored number. As a theoretical example, you could have
an object with an attribute representing the Earth's population. If this value was not able to be stored inside your
object, your custom getter routine could initiate a global census before returning the result. A custom setter for the
earth's population might do something nasty if the value was set to zero. If you are not a misanthrope, you can take
advantage of the ability to set such an attribute to be read-only.

10.1.2 Defining Attributes

Attributes are defined when you are defining methods in your initialization routine. You can define your attributes
before your methods if you like, but by convention, they are typically defined after the methods. For each definition,
you'll specify the name, size, and offset of the corresponding member in your object's data structure that will hold
the data. For example, let's say we have an object defined as follows:

typedef struct _myobject {

t_object m_ob;
long m_targetaddress;
t_symbol *m_shipname;
char m_compatmode;
} t_myobject;

We want to create attributes for m_targetaddress, m_shipname, and m_compatmode. For each data type (and a
few others), there are macros in ext_obex_util.h that will save a fair amount of typing. So, for example, we can
define an attribute for m_targetaddress that uses CLASS_ATTR_LONG. Here are attribute definitions for all of the
members of our data structure above.

CLASS_ATTR_LONG(c, "targetaddress", 0, t_myobject, m_targetaddress);

CLASS_ATTR_SYM(c, "shipname", 0, t_myobject, m_shipname);
CLASS_ATTR_CHAR(c, "compatibilitymode", 0, t_myobject, m_compatmode);

10.1.3 Attributes With Custom Getters and Setters

In some cases, it is not enough to have Max read and write data in your object directly. In some cases (as in the
world population example above) you may have data you need to calculate before it can be returned as a value.
In other cases, you may need to do something to update other object state when an attribute value changes. To
handle these challenges, you can define custom attribute getter and setter routines. The getter will be called when
the value of your attribute is accessed. The setter will be called when someone changes the value of your attribute.
As an example, suppose we have an object that holds onto an array of numbers, and we want to create an attribute
for the size of the array. Since we'll want to resize the array when the attribute value changes, we will define a
custom setter for our attribute. The default getter is adequate if we store the array size in our object, but since we
want to illustrate how to write an attribute getter, we'll write the code so that the array size is computed from the size
of the memory pointer we allocate. First, here is our object's data structure:

typedef struct _myobject {

t_object m_ob;
long *m_data;
} t_myobject;

We also have prototypes for our custom attribute setter and getter:

t_max_err myobject_size_get(t_myobject *x, t_object *attr, long *argc,

t_atom **argv);
t_max_err myobject_size_set(t_myobject *x, t_object *attr, long argc,
t_atom *argv);

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

10.2 Receiving Notifications 33

Here is how we define our attribute using CLASS_ATTR_ACCESSORS macro to define the custom setter and
getter. Because we aren't really using an "offset" due to the custom setter and getter, we can pass any data
structure member as a dummy. (Only the default attribute getter and setter will use this offset, and they are out of
the picture.)

CLASS_ATTR_LONG(c, "size", 0, t_myobject, m_ob);

CLASS_ATTR_ACCESSORS(c, "size", myobject_size_get, myobject_size_set);

Now, here is an implementation of the custom setter for the array size. For the setter, we use the handy Max API
function sysmem_resizeptr so we can effectively "resize" our array and copy the data into it in one step. The setter
uses atoms, so we have to obtain the value from the first item in the argv array.

t_max_err myobject_size_set(t_myobject *x, t_object *attr, long argc,

t_atom *argv)
{
long size = atom_getlong(argv);

if (size < 0) // bad size, don’t change anything

return 0;

if (x->m_data)
x->m_data = (long *)sysmem_resizeptr((char *)x->m_data, size * sizeof(long));
else // first time alloc
x->m_data = (long *)sysmem_newptr(size * sizeof(long));
return 0;
}

The getter also uses atoms for access, but we are returning a pointer to an array of atoms. The caller of the getter
has the option to pre-allocate the memory (passing in the length in argc and the pointer to the memory in argv) or
pass in 0 for argc and set the contents of argv to NULL and have the getter allocate the memory. The easiest way
to handle this case is to call the utility function atom_alloc, which will figure out what was passed in and allocate
memory for a returned atom if necessary.

t_max_err myobject_size_get(t_myobject *x, t_object *attr, long *argc,

t_atom **argv)
{
char alloc;
long size = 0;

atom_alloc(argc, argv, &alloc); // allocate return atom

if (x->m_data)
size = sysmem_ptrsize((char *)x->m_data) / sizeof(long); // calculate array size
based on ptr size

atom_setlong(*argv, size);
return 0;
}

10.2 Receiving Notifications

As an alternative to writing a custom setter, you can take advantage of the fact that objects receive a "notify"
message whenever one of their attributes is changed. The prototype for a notify method is as follows:

t_max_err myobject_notify(t_myobject *x, t_symbol *s, t_symbol *msg, void *sender,

void *data);

Add the following to your class initialization so your notification method will be called:

class_addmethod(c, (method)myobject_notify, "notify",

A_CANT, 0);

The notify method can handle a variety of notifications (more documentation on this is coming soon!), but the one
we're interested in is "attr_modified" – the notification type is passed to the notify method in the msg argument.
Here is an example of a notify method that prints out the name of the attribute that has been modified. You could
take any action instead. To obtain the name, we interpret the data argument to the notify method as an attribute
object. As an attribute is a regular Max object, we can use object_method to send it a message. In the case we are
sending the message getname to the attribute object to obtain its name.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

34 Sending Messages, Calling Methods

t_max_err myobject_notify(t_myobject *x, t_symbol *s, t_symbol *msg, void *sender,

void *data)
{
t_symbol *attrname;

if (msg == gensym("attr_modified")) { // check notification type

attrname = (t_symbol *)object_method((t_object *)data,
gensym("getname")); // ask attribute object for name
object_post((t_object *)x, "changed attr name is %s",attrname->
s_name);
}
return 0;
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 11

Anatomy of a UI Object

Max user interface objects are more complex than normal non-user-interface objects.
If you have nothing in particular to display, or do not need to create a unique interface for user interaction or editing,
it would be better to avoid writing one. However, if you want the details, we have them for you!
In order to create a user interface object, you'll need to be familiar with Attributes, as they are used extensively. If you
examine a toggle object in the inspector in Max, you will see a few attributes that have been defined as belonging
to the toggle class, namely:

• Background Color

• Check Color

• Border Color

We'll show how attributes are defined and described so that the inspector can edit them properly.
In addition to attributes, user interface objects draw in a box and respond to user events such as mouse clicks and
keyboard events. We'll show how to implement drawing an object's paint method as well user interaction in the
mousedown, mousedrag, and mouseup methods.
This chapter only covers basic drawing of lines and filled rectangles. But you can take advantage of a complete
graphics API called jgraphics, intended to be used in a user interface object's paint method. We discuss JGraphics
in more detail in a separate chapter. You may also find the jgraphics.h header file descriptions of the set of functions
helpful.
The SDK examples contain two user interface projects – the one we'll discuss in this chapter is called uisimp and is
a version of the toggle object with a more complicated check box and user interaction. The second project is called
pictmeter∼, a more advanced object that uses audio as well as image files.
The uisimp object differs from the toggle object in a couple of ways:

• it tracks the mouse even when it isn't down and "looks excited" when the mouse passes over it

• it tracks the mouse while the user is holding the mouse down to show a sort of "depressed" appearance when
turning the toggle on

• the new toggle state value is sent out when the mouse is released rather than when the mouse is down. In
addition, the uisimp object tracks the mouse and does not change the state if the mouse is released outside
of the object's box

• it doesn't have rounded corners

• it has a solid square for a "checked state" instead of an X

Otherwise, it acts largely as the toggle does.

The first thing we suggest you do is build the uisimp object and test it out. Once the object is properly building, type
"uisimp" into an object box and you can try it out.
36 Anatomy of a UI Object

11.1 Required Headers

UI objects require that you include two header files, jpatcher_api.h and jgraphics.h:

#include "jpatcher_api.h"
#include "jgraphics.h"

The header file jpatcher_api.h includes data structures and accessor functions required by UI objects. The header
file jgraphics.h includes data structures and functions for drawing.

11.2 UI Object Data Structure

The first part of a UI object is a t_jbox, not a t_object. You should generally avoid direct access to fields of a t_jbox,
particularly when changing values, and use the accessor functions defined in jpatcher_api.h. For example, if you
change the rectangle of a box without using the accessor function jbox_set_rect(), the patcher will not be notified
properly and the screen will not update.
Following the t_jbox, you can add other fields for storing the internal state of your object. In particular, if you are
going to be drawing something using color, you will want to create attributes that reference fields holding colors in
your object. We'll show you how to do this below. Here is the declaration of the t_uisimp data structure.

typedef struct _uisimp

{
t_jbox u_box; // header for UI objects
void *u_out; // outlet pointer
long u_state; // state (1 or 0)
char u_mouseover; // is mouse over the object
char u_mousedowninside; // is mouse down within the object
char u_trackmouse; // if non-zero, track mouse when button not down
t_jrgba u_outline; // outline color
t_jrgba u_check; // check (square) color
t_jrgba u_background; // background color
t_jrgba u_hilite; // highlight color (when mouse is over and when clicking to
check box)
} t_uisimp;

The t_jrgba structure defines a color with four doubles for red, green, blue, and alpha. Each component ranges from
0-1. When red, green, and blue are all 0, the color is black; when red, green, and blue are 1, the color is white. By
defining color attributes using t_jrgba structures, you will permit the user to use the standard color picker from the
inspector to configure colors for your object.
The structure members u_mouseover and u_mousedowninside are used to signal the code that paints the toggle
from the code that handles mouse interaction. We'll discuss this more in the "interaction strategy" section below.

11.3 Initialization Routine for UI Objects

Once you've declared your object's struct, you'll write your initialization ( ext_main() ) routine to set up the class,
declaring methods and attributes used by UI objects.
The first addition to the class initialization of a normal Max object you need to make is a call to jbox_initclass(). This
adds standard methods and attributes common to all UI objects. Here's how you should to it:

c = class_new("uisimp", (method)uisimp_new, (method)uisimp_free, sizeof(t_uisimp), 0L,

A_GIMME, 0);

c->c_flags |= CLASS_FLAG_NEWDICTIONARY;
jbox_initclass(c, JBOX_FIXWIDTH | JBOX_COLOR);

The line c->c_flags |= CLASS_FLAG_NEWDICTIONARY is required, but the flags passed to jbox_initclass – JB←-
OX_FIXWIDTH and JBOX_COLOR – are optional. JBOX_FIXWIDTH means that when your object is selected in a
patcher, the Fix Width menu item will be enabled to resize your object to its class's default dimensions. We'll specify
the default dimensions in a moment. JBOX_COLOR means that your object will be given a color attribute so that

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

11.4 UI Object Methods 37

it can be edited with the color picked shown by the Color... menu item. This is a way to edit a "basic" color of your
object without opening the inspector. If neither of these behaviors apply to your object, feel free to pass 0 for the
flags argument to jbox_initclass().

11.4 UI Object Methods

Next we need to bind a few standard methods. The only required method for UI objects is paint, which draws the
your object's content when its box is visible and needs to be redrawn.

class_addmethod(c, (method)uisimp_paint, "paint",

A_CANT, 0);

We'll discuss the paint method in detail below. It makes use of the JGraphics API, which is described in more detail
in its own chapter.
Our uisimp toggle will respond to mouse gestures, so we will define a set of mouse handling methods.

class_addmethod(c, (method)uisimp_mousedown, "mousedown",

A_CANT, 0);
class_addmethod(c, (method)uisimp_mousedrag, "mousedrag",
A_CANT, 0);
class_addmethod(c, (method)uisimp_mouseup, "mouseup",
A_CANT, 0);
class_addmethod(c, (method)uisimp_mouseenter, "mouseenter",
A_CANT, 0);
class_addmethod(c, (method)uisimp_mouseleave, "mouseleave",
A_CANT, 0);
class_addmethod(c, (method)uisimp_mousemove, "mousemove",
A_CANT, 0);
class_addmethod(c, (method)uisimp_mousewheel, "mousewheel",
A_CANT, 0);

mousedown is sent to your object when the user clicks on your object – in other words, when the mouse is moved
over the object and the primary mouse button is depressed. mousedrag is sent after an initial mousedown when the
mouse moves and the button is still held down from the click. mouseup is sent when the mouse button is released
after a mousedown is sent. mouseenter is sent when the mouse button is not down and the mouse moves into
your object's box. mousemove is sent – after a mouseenter – when the mouse button is not down but the mouse
position changes inside your object's box. mouseleave is sent when the mouse button is not down and the mouse
position moves from being over your object's box to being outside of it. mousewheel is sent when information about
the scrollwheel on the mouse (or scrolling from another source such as a trackpad) is transmitted while the cursor
is hovering over your object.
You are not obligated to respond to any of these messages. You could, for example, only respond to mousedown
and ignore the other messages.
It might be helpful to summarize mouse messages in the following "rules" (although normally it's not necessary to
think about them explicitly):

• mousedown will always be followed by mouseup, but not necessarily by mousedrag if the button press is rapid
and there is no movement while the mouse button is pressed.

• mouseenter will always be followed by mouseleave, but

• mouseenter will always precede mousemove

• mouseleave will be sent only after a mouseenter is sent

• You cannot count on any particular relationship between the mousedown / mousedrag / mouseup sequence
and the mouseenter / mousemove / mouseleave sequence.

We'll look at the actual implementation of mouse handling methods below.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

38 Anatomy of a UI Object

11.5 Defining Attributes

After the declaration of standard methods, your object will define its own attributes. By using what we call "attribute
attributes" you can further describe attributes so that they can be appropriately displayed and edited in the inspector
as well as saved in a patcher (or not). You can also set default values for attributes that are automatically copied to
your object when it is instantiated, and mark an attribute so that your object is redrawn when its value changes.
As a convenience, we've defined a series of macros in ext_obex_util.h (which is included when your object includes
ext_obex.h) that reduce the amount of typing needed to define attributes and attribute attributes.
Most UI object attributes are offset attributes; that is, they reference a location in your object's data structure by
offset and size. As an example, uisimp has a char offset attribute called trackmouse that specifies whether the
object will change the object's appearance when the mouse moves over it. Here's how this is defined:

CLASS_ATTR_CHAR(c, "trackmouse", 0, t_uisimp, u_trackmouse);

CLASS_ATTR_STYLE_LABEL(c, "trackmouse", 0, "onoff", "Track Mouse");
CLASS_ATTR_SAVE(c, "trackmouse", 0);

The first line, CLASS_ATTR_CHAR, defines a char-sized offset attribute. If you look at the declaration of t_←-
uisimp, you can see that the u_trackmouse field is declared to be a char. The CLASS_ATTR_CHAR macro take
five arguments.

• The first argument is the class for which the attribute is being declared.

• The second argument is the name of the attribute. You can use send a message to your object with this name
and a value and set the attribute.

• The third argument is a collection of attribute flags. For the attributes (and attribute attributes) we'll be defining
in the uisimp object, the flags will be 0, but you can use them to make attributes read-only with ATTR_SET←-
_OPAQUE_USER.

• The fourth argument is the name of your object's structure containing the field you want to use for the attribute

• The fifth argument is the field name you want to use for the attribute

The fourth and fifth arguments are used to calculate the offset of the beginning of the field from the beginning of the
structure. This allows the attribute to read and write the memory occupied by the field directly.
The second line, CLASS_ATTR_STYLE_LABEL, defines some attribute attributes for the trackmouse attribute. T←-
His macro takes five arguments as well:

• The first argument is the class for which the attribute attributes are being declared.

• The second argument is the name of the attribute, which should have already been defined by a CLASS_←-
ATTR_CHAR or similar attribute declaration

• The third argument is usually 0 – it is an attribute flags argument for the attribute attributes

• The fourth argument is the style of the attribute. "onoff" is used here for a setting in your object that will be a
toggle. By using the onoff style the trackmouse attribute will appear with a checkbox in the inspector window.
Effectively, this macro defines an attribute called "style" that is attached to the "trackmouse" attribute and set
its value to the symbol "onoff" in one step.

• The fifth argument is a string used as a descriptive label for the attribute that appears in the inspector and
other places in the Max user interface. If you don't supply a label, the attribute name will be shown. The string
is used as the value of a newly created "label" attribute attribute.

The category attribute attribute is used to organize your object's attributes in the inspector window. For the track-
mouse attribute, we use the "Behavior" category, and for the color attributes discussed below, we use "Color" – look
at the inspector category tabs for a few UI objects that come with Max for suggested standard category names.
You're free to create your own.
To define a category for a single attribute, you can use the CLASS_ATTR_CATEGORY macro:

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

11.5 Defining Attributes 39

CLASS_ATTR_CATEGORY(c, "trackmouse", 0, "Behavior");

To define a category for a series of attributes, you can use CLASS_STICKY_ATTR, which applies the current value
of a specified attribute attribute to any attributes subsequently defined, until a CLASS_STICKY_ATTR_CLEAR is
set for an attribute attribute name. CLASS_STICKY_ATTR is used in uisimp to apply the "Color" category to a set
of three color attributes.

CLASS_STICKY_ATTR(c, "category", 0, "Color");

Color attributes are defined using CLASS_ATTR_RGBA. The uisimp object defines four color attributes. Here is the
first, called bgcolor:

CLASS_ATTR_RGBA(c, "bgcolor", 0, t_uisimp, u_background);

CLASS_ATTR_DEFAULTNAME_SAVE_PAINT(c, "bgcolor", 0, "1. 1. 1. 1.");
CLASS_ATTR_STYLE_LABEL(c,"bgcolor",0,"rgba","Background Color");

The difference between CLASS_ATTR_RGBA and CLASS_ATTR_CHAR for defining an attribute is that CLASS←-
_ATTR_RGBA expects the name of a structure member declared of type t_jrgba rather than type char. When set,
the attribute will assign values to the four doubles that make up the components of the color.
The next line uses the CLASS_ATTR_DEFAULTNAME_SAVE_PAINT macro. This sets three things about the
bgcolor attribute. First it says that the color attribute bgcolor can be assigned a default value via the object de-
faults window. So, if you don't like the standard white defined by the object, you can assign you own color for the
background color of all newly created uisimp objects. The four values 1 1 1 1 supplied as the last argument to C←-
LASS_ATTR_DEFAULTNAME_SAVE_PAINT specify the "standard" default value that will be used for the bgcolor
attribute in the absence of any overrides from the user.
The SAVE aspect of this macro specifies that this attribute's values should be saved with the object in a patcher. A
patcher file saves an object's class, location and connections, but it can also save the object's appearance or any
other attribute value you specify, by using the "save" attribute attribute.
The PAINT aspect of this macro provides the ability to have your object redrawn whenever this attribute (bgcolor)
changes. However, to implement auto-repainting on attribute changes, you'll need to add the following code when
initializing your class:

class_addmethod(c, (method)jbox_notify, "notify",

A_CANT, 0);

The function jbox_notify() will determine whether an attribute that has caused a change notification to be sent has
its paint attribute attribute set, and if so, will call jbox_redraw(). If you write your own notify method because you
want to respond to changes in attributes or other environment changes, you ∗must∗ call jbox_notify() inside of it.

11.5.1 Standard Color Attribute

At the beginning of our initialization routine, we passed JBOX_COLOR as a flag to jbox_initclass(). This adds an
attribute to our object called color, which uses storage provided in the t_jbox to keep track of a color for us. The
color attribute is a standard name for the "most basic" color your object uses, and if you define it, the Color menu
item in the Object menu will be enabled when your object is selected, permitting the user to change the color without
opening the inspector.
If you use JBOX_COLOR, you don't need to define the color attribute using CLASS_ATTR_RGBA – jbox_initclass()
will do it for you. However, the color attribute comes unadorned, so you are free to enhance it with attribute attributes.
Here's what uisimp does:

CLASS_ATTR_DEFAULTNAME_SAVE_PAINT(c, "color", 0, "0. 0. 0. 1.");

CLASS_ATTR_STYLE_LABEL(c,"color",0,"rgba","Check Color");

11.5.2 Setting a Default Size

Another attribute defined for your object by jbox_initclass() is called patching_rect. It holds the dimensions of your
object's box. If you want to set a standard size for new instances of your object, you can give the patching_rect a

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

40 Anatomy of a UI Object

set of default values. Use 0 0 for the first two values (x and y position) and use the next two values to define the
width and height. We want a small square to be the default size for uisimp, so we use CLASS_ATTR_DEFAULT to
assign a default value to the patching_rect attribute as follows:

CLASS_ATTR_DEFAULT(c,"patching_rect",0, "0. 0. 20. 20.");

11.6 New Instance Routine

The UI object new instance routine is more complicated than that of a normal Max object. Each UI object is passed
a t_dictionary (a hierarchically structured collection of data accessed by symbolic names) containing the information
needed to instantiate an instance. For UI objects, data elements in the dictionary correspond to attribute values.
For example, if your object saved an attribute called "bgcolor" you will be able to access the saved value in your new
instance routine from the dictionary using the same name bgcolor.
If the instance is being created from the object palette or by the typing the name of your object into an object box,
the dictionary will be filled in with default values. If the object is being created by reading a patcher file, the dictionary
will be filled in with the saved attributes stored in the file. In most cases, you don't need to work with the dictionary
directly, unless you've added proprietary non-attribute information to your object's dictionary that you want to look
for and extract. However, you do need to pass the dictionary to some standard routines, and initialize everything in
the right order.
Let's take a look at the pattern you should follow for your object's new instance routine.
First, the new instance routine is declared as follows:

void *uisimp_new(t_symbol *s, long argc, t_atom *argv);

We will get the dictionary that defines the object out of the arguments passed in argc, argv. (The symbol argument
s is the name of the object.) If obtaining the dictionary fails, we should return NULL to indicate we didn't make an
instance.

void *uisimp_new(t_symbol *s, long argc, t_atom *argv);

{
t_uisimp *x = NULL;
t_dictionary *d = NULL;
long boxflags;

if (!(d = object_dictionaryarg(argc,argv)))
return NULL;

Next, we allocate a new instance of the object's class:

x = (t_uisimp *)object_alloc(s_uisimp_class);

Then we need to initialize the options for our box. Our object uses the options that are not commented out.

boxflags = 0
| JBOX_DRAWFIRSTIN
| JBOX_NODRAWBOX
| JBOX_DRAWINLAST
| JBOX_TRANSPARENT
// | JBOX_NOGROW
| JBOX_GROWY
// | JBOX_GROWBOTH
// | JBOX_HILITE
// | JBOX_BACKGROUND
| JBOX_DRAWBACKGROUND
// | JBOX_NOFLOATINSPECTOR
// | JBOX_MOUSEDRAGDELTA
// | JBOX_TEXTFIELD
;

Here is some more detail about each of the box flags.

We pass the flags along with a pointer to our newly created instance and the argc, argv arguments to jbox_new().
The name is a little misleading. jbox_new() does not instantiate your box. As we explained above, your UI object
has a t_jbox at the beginning. jbox_new() just initializes the t_jbox for you. jbox_new() doesn't know about the other
stuff in your object's data structure that comes after the t_jbox. You'll have to initialize the extra items yourself.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

11.7 Dynamic Updating 41

jbox_new((t_jbox *)x, boxflags, argc, argv);

Once jbox_new() has been called, you then assign the b_firstin pointer of your t_jbox header to point to your object.
Essentially this assigns the object that will receive messages from objects connected to your leftmost inlet (as well
as other inlets via inlets or proxies you create). This step is easily forgotten and will cause most things not to work
until you remember it. jbox_new() will obtain the attributes common to all boxes such as the patching_rect, and
assign them to your object for you.

x->u_box.b_firstin = (void *)x;

Next, you are free to initialize any members of your object's data structure, as well as declare inlets. These steps
are the same for UI objects as for non-UI objects.

x->u_mousedowninside = x->u_mouseover = x->u_state = 0;

x->u_out = intout((t_object *)x);

Once your object is in a safe initialized state, call attr_dictionary_process() if you've defined any attributes. This will
find the attributes in the dictionary your object received, then set them to the values stored in the dictionary. There
is no way to guarantee the order in which the attributes will be set. If this a problem, you can obtain the attribute
values "by hand" and assign them to your object.
Note that you do not need to call attr_dictionary_process() if you have not defined any attributes. jbox_new() will
take care of setting all attributes common to all UI objects.

attr_dictionary_process(x,d);

As the last thing to do before returning your newly created UI object, and more specifically after you've initialized
everything to finalize the appearance of your object, call jbox_ready(). jbox_ready() will paint your object, calculate
the positions of the inlets and outlets, and perform other initialization tasks to ensure that your box is a proper
member of the visible patcher.
If your object does not appear when you instantiate it, you should check whether you do not have a jbox_ready()
call.

jbox_ready((t_jbox *)x);

Finally, as with any instance creation routine, the newly created object will be returned.

return x;

11.7 Dynamic Updating

Drawing anything to the screen must be limited to your paint method (this was not the case with the previous UI
object API in Max). If you want to redraw something, you need to call jbox_redraw() to cause the screen to be
redrawn. This is necessary because your object is part of a compositing user interface that must be managed by
the patcher as a whole to avoid screen artifacts. The jbox_redraw() routine calculates the area of the screen that
needs to be redrawn, then informs the Mac or Windows "window manager" to mark this area as invalid. At some
later point in time, the OS will invoke the patcher's paint routine, which will dispatch to all of the boxes inside the
invalid area according to the current Z-order of all the boxes. Boxes that are in the background are drawn first,
so that any transparent or semi-transparent boxes can be drawn on top of them. In addition, unless you specify
otherwise, the last drawn image of a box is cached in a buffer, so that your paint method will only be called when
you explicitly invalidate your object's content with jbox_redraw(). In other words, you can't count on "global patcher
drawing" to invoke your paint method.
The basic strategy you'll want to use in thinking about redrawing is that you will set internal state in other methods,
then call jbox_redraw(). The paint method will read the internal state and adjust its drawing appropriately. You'll see
this strategy used in the uisimp object as it tracks the mouse.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

42 Anatomy of a UI Object

11.8 The Paint Method

Your object's paint method uses the jgraphics API to draw. The header file, jgraphics.h, provides a description of
each of the routines in the API. Here we will only discuss general principles and features of drawing with uisimp's
relatively simple paint method. There is also a jgraphics example UI object that contains a number of functions
showing how various drawing tasks can be performed.
Drawing in Max is resolution-independent. The "size" of your object's rectangle is always the pixel size when the
patcher is scaled to 100% regardless of the zoom level, and any magnification or size reduction to the actual screen
is automatically handled by matrix transforms. Another thing that is handled automatically for you is drawing to
multiple views. If a patcher is invisible (i.e., a subpatcher that has not been double-clicked), it does not have any
views. But if it is visible, a patcher can have many patcherviews. If your UI object box is in a patcher with multiple
views open, your paint method will be called once for each view, and will be passed different a patcherview object
each time. For most objects, this will pose few problems, but for objects to work properly when there are anywhere
from zero to ten views open, they cannot change their internal state in the paint method, they can only read it. As
an example, if your object had a boolean "painted" field in its structure that would be set when the paint method
had finished, it would not work properly in the cases where the box was invisible or where it was shown in multiple
patcher views, because it would either be set zero or more than once.
The first step for any paint method is to obtain the t_jgraphics object from the patcherview object passed to the paint
method. The patcherview is an opaque t_object that you will use to access information about your box's rectangle
and its graphics context. A patcherview is not the same thing as a patcher; as mentioned above, there could be
more than one patcherview for a patcher if it has multiple views open.

void uisimp_paint(t_uisimp *x, t_object *patcherview)

{
t_rect rect;

t_jgraphics *g = (t_jgraphics*)
patcherview_get_jgraphics(patcherview); // obtain graphics context

After obtaining the t_jgraphics object, the next thing that you'll need to do is determine the rectangle of your box. A
view of a patcher may be in either patching or presentation mode. Since each mode can have its own rectangle, it
is necessary to use the patcherview to obtain the rectangle for your object.

jbox_get_rect_for_view((t_object *)x, patcherview, &rect);

The t_rect structure specifies a rectangle using the x and y coordinates of the top left corner, along with the width
and height. However, the coordinates of the t_jgraphics you'll be using to draw into always begin at 0 for the top left
corner, so you'll only care about the width and height, at least for drawing.
The first thing we'll draw is just an outline of our box using the value of the outline color attribute. First we'll set the
color we want to use, then make a rectangular path, then finally we'll stroke the path we've made.
With calls such as jgraphics_rectangle(), the rectangular shape is added to the existing path. The initial path is
empty, and after calling jgraphics_stroke() or jgraphics_fill(), the path is again cleared. (If you want to retain the
path, you can use the jgraphics_stroke_preserve() and jgraphics_fill_preserve variants().)

jgraphics_set_source_jrgba(g, &x->u_outline);
jgraphics_set_line_width(g, 1.);
jgraphics_rectangle(g, 0., 0., rect.width, rect.height);
jgraphics_stroke(g);

You do not need to destroy the path before your paint method is finished. This will be done for you, but the fact
that the path does not survive after the paint method is finished means you can't make a path and then store it
without copying it first. Such a strategy is not recommended in any case, since your object's rectangle might change
unpredictably from one paint method invocation to the next, which will likely cause your path to be the wrong shape
or size.
The next feature of the paint method is to draw an inner outline if the mouse is moved over the box. Detecting
the mouse's presence over the box happens in the mouseenter / mouseleave methods described below – but
essentially, we know that the mouse is over our object if the u_mouseover has been set by these mouse tracking
methods.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

11.9 Handling Mouse Gestures 43

To draw a rectangle that is inset by one pixel from the box rectangle, we use the rectangle starting at 1, 1 with a
width of the box width - 2 and a height of the box height - 2.

// paint "inner highlight" to indicate mouseover

if (x->u_mouseover && !x->u_mousedowninside) {
jgraphics_set_source_jrgba(g, &x->u_hilite);
jgraphics_set_line_width(g, 1.);
jgraphics_rectangle(g, 1., 1., rect.width - 2, rect.
height - 2);
jgraphics_stroke(g);
}

Some similar code provides the ability to show the highlight color when the user is about to check (turn on) the
toggle:

if (x->u_mousedowninside && !x->u_state) { // paint hilite color

jgraphics_set_source_jrgba(g, &x->u_hilite);
jgraphics_rectangle(g, 1., 1., rect.width - 2, rect.
height - 2);
jgraphics_fill(g);
}

Finally, we paint a square in the middle of the object if the toggle state is non-zero to indicate that the box has been
checked. Here we are filling a path instead of stroking it. Note also that we use the call jbox_get_color() to get the
"standard" color of our object that is stored inside the t_jbox. As we've specified by using the JBOX_COLOR flag for
jbox_initclass() in our initialization routine, the color obtained by jbox_get_color() for the "check" (really just a square
of solid color) is the one the user can change with the Color... item in the Object menu.

if (x->u_state) {
t_jrgba col;

jbox_get_color((t_object *)x, &col);

jgraphics_set_source_jrgba(g, &col);
if (x->u_mousedowninside) // make rect bigger if mouse is down and we are unchecking
jgraphics_rectangle(g, 3., 3., rect.width - 6, rect.
height - 6);
else
jgraphics_rectangle(g, 4., 4., rect.width - 8, rect.
height - 8);
jgraphics_fill(g);
}

Clearly, a quick perusal of the jgraphics.h header file will demonstrate that there is much more to drawing than we've
discussed here. But the main purpose of the uisimp paint method is to show how to implement "dynamic" graphics
that follow the mouse. Now we'll see the mouse tracking side of the story.

11.9 Handling Mouse Gestures

When the mouse is clicked, dragged, released, or moved inside its box, your object will receive messages. In the
uisimp example we've defined methods for most of the mouse gesture messages available, and we've implemented
them to change internal state in the object, then call jbox_redraw() to repaint the object to reflect the new state. This
strategy produces a "dynamic" appearance of a gadget users associate with a typical graphical interface – in this
case a toggle checkbox.
All mouse gesture methods are declared in the same way:

void myobect_mouse(t_myobject *x, t_object *patcherview, t_pt pt, long modifiers);

Let's first look at the most commonly implemented mouse gesture handler, the mousedown method that responds
to an initial click on the object. As you can see, it is very simple; it merely sets u_mousedowninside to true, then
calls jbox_redraw(), causing the box to be repainted. We've defined this toggle not to change the actual state until
the mouse is released (unlike the standard Max toggle object), but we do want to give the user some feedback on
the initial mouse down that something is going to happen. If you look back at the paint method, you can see that
u_mousedowninside is used to change the way the object is painted to give it a "pending state change" appearance
that will be finalized when the mouse is released inside the box.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

44 Anatomy of a UI Object

void uisimp_mousedown(t_uisimp *x, t_object *patcherview, t_pt pt, long modifiers)

{
x->u_mousedowninside = true; // wouldn’t get a click unless it was inside the box
jbox_redraw((t_jbox *)x);
}

If we test the mouse position to ensure that it is inside the box when it is released, we provide the opportunity for
the user to cancel the act of toggling the state of the object by moving the cursor outside of the box before releasing
the button. To provide feedback to the user that this is going to happen, we've implemented a mousedrag method
that performs this test and redraws the object if the "mouse inside" condition has changed from its previous state.
The mousedrag message will be sent to your object as long as the mouse button is still down after an initial click
and the cursor has moved, even if the cursor moves outside of the boundaries of your object's box.
Note that, as with the paint method, we use the patcherview to get the current box rectangle. We can then test the
point we are given to see if it is inside or outside the box.

void uisimp_mousedrag(t_uisimp *x, t_object *patcherview, t_pt pt, long modifiers)

{
t_rect rect;

// test to see if mouse is still inside the object

jbox_get_rect_for_view((t_object *)x, patcherview, &rect);

// redraw if changed
if (pt.x >= 0 && pt.x <= rect.width && pt.y >= 0 && pt.y <= rect.
height) {
if (!x->u_mousedowninside) {
x->u_mousedowninside = true;
jbox_redraw((t_jbox *)x);
}
} else {
if (x->u_mousedowninside) {
x->u_mousedowninside = false;
jbox_redraw((t_jbox *)x);
}
}
}

Our mouseup method uses the last value of u_mousedowninside as the determining factor for whether to toggle the
object's internal state. If u_mousedowninside is false, no state change happens. But if it is true, the state changes
and the new state value is sent out the object's outlet (inside uisimp_bang()).

if (x->u_mousedowninside) {
x->u_state = !x->u_state;
uisimp_bang(x);
x->u_mousedowninside = false;
jbox_redraw((t_jbox *)x);
}

Finally, we've implemented mouseenter, mousemove, and mouseleave methods to provide another level of "mouse
over" style highlighting for the object. Rather than changing u_mousedowninside, a u_mouseover field is set when
the mouseenter message is received, and cleared when the mouseleave method is received. And again, after this
variable is manipulated, we repaint the box with jbox_redraw().

void uisimp_mouseenter(t_uisimp *x, t_object *patcherview, t_pt pt, long modifiers)

{
x->u_mouseover = true;
jbox_redraw((t_jbox *)x);
}

void uisimp_mouseleave(t_uisimp *x, t_object *patcherview, t_pt pt, long modifiers)

{
x->u_mouseover = false;
jbox_redraw((t_jbox *)x);
}

11.10 Freeing a UI Object

If your object has created any clocks or otherwise allocated memory that should be freed when the object goes
away, you should handle this in the free routine. But, most importantly, you must call the function jbox_free(). If

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

11.10 Freeing a UI Object 45

your UI object doesn't need to do anything special in its free routine, you can pass jbox_free() as the free routine
argument to class_new() in your initialization routine. We chose not to do this, since having an actual function
permits easy modification should some memory need to be freed at some point in the future evolution of the object.

void uisimp_free(t_uisimp *x)

{
jbox_free((t_jbox *)x);
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

46 Anatomy of a UI Object

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 12

File Handling

Max contains a cross-platform set of routines for handling files.

These routines permit you to search for files, show file open and save dialogs, as well as open, read, write, and
close them. The file API is based around a "path identifier" – a number that describes the location of a file. When
searching or reading a file, path identifiers can be either a folders or collectives. Path identifiers that are negative (or
zero) describe actual folders in the computer's file system, while path identifiers that are positive refer to collectives.
A basic thing you might want to do make your object accept the read message in a manner similar to existing Max
objects. If the word read is followed by no arguments, a file dialog appears for the user to choose a file. If read is
followed by an argument, your object will search for the file. If a file is found (or chosen), your object will open it and
read data from it.
First, make your object accept the read message. The simplest way to make the filename argument optional is to
use the A_DEFSYM argument type specifier. When the symbol argument is not present, Max passes your method
the empty symbol.

class_addmethod(c, (method)myobject_read, "read", A_DEFSYM, 0);

The next requirement for any method that reads files is that it must defer execution to the low-priority thread, as
shown in the following implementation, where the filename argument is passed as the symbol argument to defer.

void myobject_read(t_myobject *x, t_symbol *s)

{
defer(x, (method)myobject_doread, s, 0, NULL);
}

The myobject_doread() function compares the filename argument with the empty symbol – if the argument was not
supplied, the open_dialog() is used, otherwise, we call locatefile_extended() to search for the file. This object looks
for text files, so we use a four-character code 'TEXT' as our file type to either open or locate. File type codes define
a set of acceptable extensions. The file max-fileformats.txt permits contains standard definitions, and you can add
your own by creating a similar text file and placing it in the init folder inside the Cycling '74 folder.

void myobject_doread(t_myobject *x, t_symbol *s)

{
t_fourcc filetype = ’TEXT’, outtype;
short numtypes = 1;
char filename[MAX_PATH_CHARS];
short path;

if (s == gensym("")) { // if no argument supplied, ask for file

if (open_dialog(filename, &path, &outtype, &filetype, 1)) // non-zero: user
cancelled
return;
} else {
strcpy(filename, s->s_name); // must copy symbol before calling locatefile_extended
if (locatefile_extended(filename, &path, &outtype, &filetype, 1)) { //
non-zero: not found
object_error(x, "%s: not found", s->s_name);
return;
}
}
48 File Handling

// we have a file
myobject_openfile(x, filename, path);
}

To open and read files, you can use the cross-platform sysfile API. Files can be opened using a filename plus path
identifier. If successfully opened, the file can be accessed using a t_filehandle. Note that "files" inside collective
files are treated identically to regular files, with the exception that they are read-only.

12.1 Reading Text Files

First, we'll implement reading the text file whose name and path identifier are passed to myobject_openfile() using
a high-level routine sysfile_readtextfile() specifically for reading text files that handles text encoding conversion for
you. If you are reading text files, using this routine is strongly recommended since converting text encodings is
unpleasant to say the least.

void myobject_openfile(t_myobject *x, char *filename, short path)

{
t_filehandle fh;
char **texthandle;

if (path_opensysfile(filename, path, &fh, READ_PERM)) {

object_error(x, "error opening %s", filename);
return
}
// allocate some empty memory to receive text
texthandle = sysmem_newhandle(0);
sysfile_readtextfile(fh, texthandle, 0, 0); // see flags explanation below
post("the file has %ld characters", sysmem_handlesize(texthandle));
sysfile_close(fh);
sysmem_freehandle(texthandle);
}

In most situations, you will pass 0 for the final two arguments to sysfile_readtextfile(). The third argument specifies
a maximum length to read, but if the value is 0, the entire file is read in, regardless of its size. The final argument
is a set of flags specifying options for reading in the text. The options concern the conversion of line breaks, text
encoding, and the ability to add a null character to the end of the data returned.
Line breaks are converted on the basis of any line break flags. When reading text files, Max converts line breaks to
"native" format, which is

\r\n

on Windows and

\n

on the Mac; this is the behavior you get if you either pass no line break flags or use TEXT_LB_NATIVE. Other
options include TEXT_LB_MAC, TEXT_LB_UNIX, or TEXT_LB_PC.
By default, text files are converted from their source encoding to UTF-8. If you do not want this conversion to occur,
you can use the TEXT_ENCODING_USE_FILE flag. This puts the burden on determining the encoding on you,
which is probably not what you want. For example, the source text file might use UTF-16 encoding, which requires
very different parsing than an 8-bit encoding.
Finally, you can have the memory returned from sysfile_readtextfile() terminated with a NULL character if you use
the TEXT_NULL_TERMINATE flag.

12.2 Reading Data Files

To read data files where you do not want to do text encoding conversion or worry about line breaks, you can use
the same technique shown above for text files, but write the myobject_openfile function using sysfile_read() instead
of sysfile_readtextfile(). This example shows how to read an entire file into a single block of memory.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

12.3 Writing Files 49

void myobject_openfile(t_myobject *x, char *filename, short path)

{
t_filehandle fh;
char *buffer;
long size;

if (path_opensysfile(filename, path, &fh, READ_PERM)) {

object_error(x, "error opening %s", filename);
return
}
// allocate memory block that is the size of the file
sysfile_geteof(fh, &size);
buffer = sysmem_newptr(size);

// read in the file

sysfile_read(fh, &size, buffer);

sysfile_close(fh);

// do something with data in buffer here

sysmem_freeptr(buffer); // must free allocated memory

}

12.3 Writing Files

Some Max objects respond to the write message to save data into a file. If there is no argument present after the
word write, a save file dialog is shown and the user specifies a file name and location. If an argument is present, it
can either specify a complete path name or a filename. In the filename case, the file is written to the current "default"
directory, which is the location where a patcher was last opened. In the full pathname case, the file is written to the
location specified by the pathname.
Here's how to implement this behavior. We'll show how to handle the message arguments, then provide text and
data file writing examples.
Message and argument handling is very similar to the way we implemented the read message above, including the
use of deferred execution.

class_addmethod(c, (method)myobject_write, "write",

A_DEFSYM, 0);

void myobject_write(t_myobject *x, t_symbol *s)

{
defer(x, (method)myobject_dowrite, s, 0, NULL);
}

The myobject_dowrite() function compares the filename argument with the empty symbol – if the argument was not
supplied, saveasdialog_extended() is used to obtain the user's choice for filename and location. Our first example
looks for text files, so we use a four-character code 'TEXT' as our file type for saving. File type codes define a set
of acceptable extensions. The file max-fileformats.txt permits contains standard definitions, and you can add your
own by creating a similar text file and placing it in the init folder inside the Cycling '74 folder.

void myobject_dowrite(t_myobject *x, t_symbol *s)

{
long filetype = ’TEXT’, outtype;
short numtypes = 1;
char filename[512];
short path;

if (s == gensym("")) { // if no argument supplied, ask for file

if (saveasdialog_extended(filename, &path, &outtype, &filetype, 1)) //
non-zero: user cancelled
return;
} else {
strcpy(filename, s->s_name);
path = path_getdefault();
}
myobject_writefile(x, filename, path);
}

Here is the text file variant of myobject_writefile() using the high-level sysfile_writetextfile() routine. We just write a
sentence as our "text file" but your object will presumably have some text data stored internally that it will write. The
buffer passed to sysfile_writetextfile() must be NULL-terminated, and will be assumed to be UTF-8 encoded.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

50 File Handling

Note that path_createsysfile() can accept a full path in the filename argument, in which case, the path argument is
ignored. This means your object's write message can either accept a filename or full pathname and you needn't do
anything special to accept both.

void myobject_writefile(t_myobject *x, char *filename, short path)

{
char *buf = "write me into a file";
long err;
t_filehandle fh;

err = path_createsysfile(filename, path, ’TEXT’, &fh);

if (err)
return;
err = sysfile_writetextfile(fh, &buf, TEXT_LB_NATIVE);
sysfile_close(fh);
}

Here is a data file variant of myobject_writefile(). It writes a small buffer of ten numbers to a file.

void myobject_writefile(t_myobject *x, char *filename, short path)

{
char *buf[10];
long count, i;
long err;
t_filehandle fh;

// create some data

for (i = 0; i < 10; i++)

buf[i] = i + 1;

count = 10;

err = path_createsysfile(filename, path, ’TEXT’, &fh);

if (err)
return;
err = sysfile_write(fh, &count, buf);
sysfile_close(fh);
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 13

Scripting the Patcher

Your object can use scripting capabilities of the patcher to learn things about its context, such as the patcher's name,
hierarchy, or the peer objects to your object in its patcher.
You can also modify a patcher, although any actions your object takes are not undoable and may not work in the
runtime version.

13.1 Knowing the Patcher

To obtain the patcher object containing your object, you can use the obex hash table. The obex (for "object exten-
sions") is, more generally, a way to store and recall data in your object. In this case, however, we are just using it in
a read-only fashion.
Note that unlike the technique discussed in previous versions of the SDK, using the obex to find the patcher works
at any time, not just in the new instance routine.

void myobject_getmypatcher(t_myobject *x)

{
t_object *mypatcher;

object_obex_lookup(x, gensym("#P"), &mypatcher);

post("my patcher is at address %lx",mypatcher);
}

The patcher is an opaque Max object. To access data in a patcher, you'll use attributes and methods.

13.1.1 Patcher Name and File Path

To obtain the name of the patcher and its file path (if any), obtain attribute values as shown below.

t_symbol *name = object_attr_getsym(patcher, gensym("name"));

t_symbol *path = object_attr_getsym(patcher, gensym("filepath"));

These attributes may return NULL or empty symbols.

13.1.2 Patcher Hierarchy

To determine the patcher hierarchy above the patcher containing your object, you can use jpatcher_get_←-
parentpatcher(). A patcher whose parent is NULL is a top-level patcher. Here is a loop that prints the name of
each parent patcher as you ascend the hierarchy.

t_object *parent, *patcher;

t_symbol *name;
52 Scripting the Patcher

object_obex_lookup(x, gensym("#P"), &patcher);

parent = patcher;
do {
parent = jpatcher_get_parentpatcher(parent);
if (parent) {
name = object_attr_getsym(parent, gensym("name"));
if (name)
post("%s",name->s_name)
}
} while (parent != NULL);

13.1.3 Getting Objects in a Patcher

To obtain the first object in a patcher, you can use jpatcher_get_firstobject(). Subsequent objects are available with
jbox_get_nextobject().
If you haven't read the Anatomy of a UI Object, we'll mention that the patcher does not keep a list of non-UI objects
directly. Instead it keeps a list of UI objects called boxes, and the box that holds non-UI objects is called a newobj.
The "objects" you obtain with calls such as jpatcher_get_firstobject() are boxes. The jbox_get_object() routine can
be used to get the pointer to the actual object, whether the box is a UI object or a newobj containing a non-UI object.
In the case of UI objects such as dials and sliders, the pointer returned by jbox_get_object() will be the same as the
box. But for non-UI objects, it will be different.
Here is a function that prints the class of every object (in a box) in a patcher containing an object.

void myobject_printpeers(t_myobject *x)

{
t_object *patcher, *box, *obj;

object_obex_lookup(x, gensym("#P"), &patcher);

for (box = jpatcher_get_firstobject(patcher); box; box =

jbox_get_nextobject(box)) {
obj = jbox_get_object(box);
if (obj)
post("%s",object_classname(obj)->s_name);
else
post("box with NULL object");
}
}

13.1.4 Iteration Using Callbacks

As an alternative to the technique shown above, you can write a callback function for use with the patcher's iteration
service. The advantage of using iteration is that you can descend into the patcher hierarchy without needing to
know the details of the various objects that may contain subpatchers (patcher, poly∼, bpatcher, etc.). If you want to
iterate only at one level of a patcher hierarchy, you can do that too.
Your iteration function is defined as follows. It will be called on every box in a patcher (and, if you specify, the
patcher's subpatchers).

long myobject_iterator(t_myobject *x, t_object *b);

The function returns 0 if iteration should continue, or 1 if it should stop. This permits you to use an iterator as a way
to search for a specific object.
Here is an example of using an iterator function:

t_object *patcher;
long result = 0;
t_max_err err;

err = object_obex_lookup(x, gensym("#P"), &patcher);

object_method(patcher, gensym("iterate"), myobject_iterator, (void *)x,

PI_WANTBOX | PI_DEEP, &result);

The PI_WANTBOX flag tells the patcher iterator that it should pass your iterator function the box, rather than the
object contained in the box. The PI_DEEP flag means that the iteration will descend, depth first, into subpatchers.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

13.2 Creating Objects 53

The result parameter returns the last value returned by the iterator. For example, if the iterator terminates early by
returning a non-zero value, it will contain that value. If the iterator function does not terminate early, result will be 0.
Assuming the iterator function receives boxes, here is an example iterator that prints out the class and scripting
name (if any) of all of the objects in a patcher. Note that the scripting name is an attribute of the box, while the class
we would like to know is of the object associated with the box.

long myobject_iterator(t_myobject *x, t_object *b)

{
t_symbol *name = object_attr_getsym(b, gensym("varname"));
t_symbol *cls = object_classname(jbox_get_object(b));

if (name)
post("%s (%s)",cls->s_name, name->s_name);
else
post("%s", cls->s_name);
return 0;
}

13.2 Creating Objects

Much of the Max user interface is implemented using patcher scripting. For example, the inspectors are patchers in
which an inspector object has been created. The file browser window has four or five separate scripted objects in it.
Even the debug window is a dynamically scripted patcher. We point this out just to inform you that creating objects in
a patcher actually works (if you get all the details right). The xxx example object shows how to use patcher scripting
to create an "editing window" similar to the ones you see when double-clicking on a table or buffer∼ object.
Creating objects in a patcher generally requires the use of a Dictionary (see discussion of UI objects above), but
there is a convenience function newobject_sprintf() that can be used to avoid some of the complexity.
To create an object, your task is to set some attributes. In the absence of any specific values, an object's attributes
will be set to some default, but you'll probably care, at the very least, about specifying the object's location. Here
is an example that creates a toggle and metro object using a combination of attribute parse syntax and sprintf. If
you're interested in creating objects with newobject_sprintf(), it may help to examine a Max document to see some
of the attribute name - value pairs used to specify objects.

t_object *patcher, *toggle, *metro;

t_max_err err;

err = object_obex_lookup(x, gensym("#P"), &patcher);

toggle = newobject_sprintf(patcher, "@maxclass toggle

@patching_position %.2f %.2f",
x->togxpos, x-> togxpos);

metro = newobject_sprintf(patcher, "@maxclass newobj @text \"metro 400\"

@patching_position %.2f %.2f",
x->metxpos, x->metypos);

Note that to create a non-UI object, you use set the maxclass attribute to newobj and the text attribute to the
contents of the object box. Attributes can be specified in any order. Using the patching_position attribute permits
you to specify only the top-left corner and use the object's default size. For text objects, the default size is based on
the default font for the patcher.
Finally, note that newobject_sprintf() returns a pointer to the newly created box, not the newly created object inside
the box. To get the object inside the box, use jbox_get_object().

13.2.1 Connecting Objects

If you'd like to script the connections between two objects, you can do so via a message to the patcher. Assuming
you have the patcher, toggle, and metro objects above, you'll create an array of atoms to send the message using
object_method_typed().

t_atom msg[4], rv;

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

54 Scripting the Patcher

atom_setobj(msg, toggle); // source

atom_setlong(msg + 1, 0); // outlet number (0 is leftmost)
atom_setobj(msg + 2, metro); // destination
atom_setlong(msg + 3, 0); // inlet number (0 is leftmost)

object_method_typed(patcher, gensym("connect"), 4, msg, &rv);

If you want to have a hidden connection, pass an optional fifth argument that is any negative number.

13.3 Deleting Objects

To delete an object in a patcher you call object_free() on the box. As of Max 5.0.6 this will properly redraw the
patcher and remove any connected patch cords.

13.4 Obtaining and Changing Patcher and Object Attributes

You can use object attribute functions to modify the appearance and behavior of objects in a patcher or the patcher
itself. Note that only a few of these attributes can be modified by the user. The C level access to attributes is much
more extensive.
Attributes whose type is object can be accessed via object_attr_getobj() / object_attr_setobj(). Attributes whose
type is char can be accessed with object_attr_getchar() / object_attr_setchar(). Attributes whose type is long can
be accessed with object_attr_getlong() / object_attr_setlong(). Attributes whose type is symbol can be accessed
via object_attr_getsym() / object_attr_setsym(). For attributes that are arrays, such as colors and rectangles, use
object_attr_getvalueof() / object_attr_setvalueof().

13.4.1 Patcher Attributes

Name Type Settable Description

box object No The box containing the
patcher (NULL for
top-level patcher)
locked char Yes (not in runtime) Locked state of the
patcher
presentation char Yes Presentation mode of the
patcher
openinpresentation char Yes Will patcher open in
presentation mode?
count long No Number of objects in a
patcher
fgcount long No Number of objects in the
patcher's foreground
layer
bgcount long No Number of objects in the
patcher's background
layer
numvews long No Number of currently open
views of the patcher
numwindowviews long No Number of currently open
window-based views of
the patcher

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

13.4 Obtaining and Changing Patcher and Object Attributes 55

firstobject object No First box in the patcher

lastobject object No Last box in the patcher
firstline object No First patch cord in the
patcher
firstview object No First view object in the
patcher
title symbol Yes Window title
fulltitle symbol No Complete title including
"unlocked" etc.
name symbol No Name (could be different
from title)
filename symbol No Filename
filepath symbol No File path
(platform-independent
file path syntax)
fileversion long No File version
noedit char No Whether patcher can be
unlocked
collective object No Collective object, if
patcher is inside a
collective
cansave char No Whether patcher can be
saved
dirty char Yes (not in runtime) Whether patcher is
modified
bglocked char Yes Whether background is
locked
rect double[4] Yes Patcher's rect (left, top,
width, height)
defrect double[4] Yes Patcher's default rect
(used when opening the
first view)
openrect double[4] Yes Fixed initial window
location
parentpatcher object No Immediate parent
patcher (NULL for
toplevel patchers)
toppatcher object No Topmost parent patcher
(NULL for toplevel
patchers)
parentclass object No Class object of parent
(patcher, poly∼,
bpatcher etc.)
bgcolor double[4] Yes Locked background color
(RGBA)
editing_bgcolor double[4] Yes Unlocked background
color (RGBA)
edit_framecolor double[4] Yes Text editing frame color
locked_iocolor double[4] Yes Locked inlet/outlet color
unlocked_iocolor double[4] Yes Unlocked inlet/outlet
color

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

56 Scripting the Patcher

boguscolor double[4] Yes Color of uninitialized

(bogus) objects
gridsize double[2] Yes Editing grid size
gridonopen char Yes Show grid on open
gridsnapopen char Yes Snap to grid on open
imprint char Yes Save default-valued
object attributes
defaultfocusbox symbol Yes Default focus box
(varname)
enablehscroll char Yes Show horizontal scrollbar
enablevscroll char Yes Show vertical scrollbar
boxanimatetime long Yes Box animation time
default_fontname symbol Yes Default font name
default_fontface long Yes Default "fake" font face (0
plain, 1, bold, 2 italic, 3
bold italic)
default_fontsize long Yes Default font size in points
toolbarvisible char Yes Show toolbar on open
toolbarheight long Yes Height of toolbar (can
use 0 for invisible)
toolbarid symbol Yes Name (in
maxinterface.json) of
toolbar, none = empty
symbol

13.4.2 Box Attributes

Name Type Settable Description

rect double[4] Settable only Changes both
patching_rect and
presentation_rect
presentation_rect double[4] Yes Presentation mode rect
patching_rect double[4] Yes Patching mode rect
position double[2] Settable only Changes both
patching_position and
presentation_position
size double[2] Settable only Changes both
patching_size and
presentation_size
patching_position double[2] Yes Patching mode position
(top, left corner)
presentation_position d[2] Yes Presentation mode
position
patching_size double[2] Yes Patching mode size
(width, height)
presentation_size double[2] Yes Presentation mode size
maxclass symbol No Name of Max class
(newobj for non-UI
objects)
object object No Associated object
(equivalent to
jbox_get_object)

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

13.4 Obtaining and Changing Patcher and Object Attributes 57

patcher object No Containing patcher

hidden char Yes Is box hidden on lock?
fontname symbol Yes Font name (if box has
font attributes or a text
field)
fontface long Yes "Fake" font face (if box
has font attribute or a text
field)
fontsize long Yes Font size (if box has font
attributes or a text field)
textcolor double[4] Yes Text color (if box has font
attributes or a text field)
hint symbol Yes Associated hint
color double[4] Yes Standard color attribute
(may not be present in all
objects)
nextobject object No Next object in the
patcher's list
prevobject object No Previous object in the
patcher's list
varname symbol Yes Scripting name
id symbol No Immutable object ID
(stored in files)
canhilite char No Does this object accept
focus?
background char Yes Include in background
ignoreclick char Yes Ignores clicks
maxfilename symbol No Filename if class is
external
description symbol No Description used by
assistance
drawfirstin char No Is leftmost inlet drawn?
growy char No Can object grow with
fixed aspect ratio?
growboth char No Can object grow
independently in width
and height?
nogrow char No Is object fixed size?
mousedragdelta char No Does object use
hidden-mouse drag
tracking (number box)
textfield object No Textfield object
associated with this box
if any
editactive char No Is object the currently
focused box in an
unlocked patcher?
prototypename symbol No Name of the prototype
file used to create this
object

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

58 Scripting the Patcher

presentation char Yes Is object included in the

presentation?
annotation symbol Yes Text shown in clue
window when mouse is
over the object
numinlets long No Number of inlets visible
numoutlets long No Number of outlets visible
outlettype symbol[] No Array of symbols with
outlet types ("signal" etc.)
To access an attribute of a non-UI object, use jbox_get_object() on the box to obtain the non-UI object first.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 14

Enhancements to Objects

14.1 Preset Support

Presets are a simple state-saving mechanism. Your object receives a preset message when state is being saved.
You respond by creating a message that will be sent back to your object when the preset is recalled.
For more powerful and general state-saving, use the pattr system described below.
To support saving a single integer in a preset, you can use the preset_int() convenience function. The preset_int()
function records an int message with the value you pass it in the preset, to be sent back to your object at a later
time.

class_addmethod(c, (method)myobject_preset, "preset", 0);

void myobject_preset(t_myobject *x)

{
preset_int(x, x->m_currentvalue);
}

More generally, you can use preset_store(). Here is an example of storing two values (m_xvalue and m_yvalue) in
a list.

preset_store("ossll", x, ob_sym(x), gensym("list"), x->m_xvalue, x->m_yvalue);

14.2 Pattr Support

In most cases, you need only to define your object's state using Attributes and it will be ready for use with Max's
pattr system. For more complex scenarios you may also wish to investigate object_notify(), object_attach(), and the
section on Receiving Notifications.

14.3 Assistance

To show descriptions of your object's inlets and outlets while editing a patcher, your object can respond to the assist
message with a function that copies the text to a string.

class_addmethod(c, (method)myobject_assist, "assist",

A_CANT, 0);

The function below has two inlets and one outlet. The io argument will be 1 for inlets, 2 for outlets. The index
argument will be 0 for the leftmost inlet or outlet. You can copy a maximum of 512 characters to the output string
s. You can use strncpy_zero() to copy the string, or if you want to format the assistance string based on a current
value in the object, you could use snprintf_zero().
60 Enhancements to Objects

void myobject_assist(t_myobject *x, void *b, long io, long index, char *s)
{
switch (io) {
case 1:
switch (index) {
case 0:
strncpy_zero(s, "This is a description of the leftmost inlet", 512);
break;
case 1:
strncpy_zero(s, "This is a description of the rightmost inlet", 512);
break;
}
break;
case 2:
strncpy_zero(s, "This is a description of the outlet", 512);
break;
}
}

14.4 Hot and Cold Inlets

Objects such as operators (+, -, etc.) and the int object have inlets that merely store values rather than performing
an operation and producing output. These inlets are labeled with a blue color to indicate they are "cold" rather than
action-producing "hot" inlets. To implement this labeling, your object can respond to the inletinfo message.

class_addmethod(c, (method)myobject_inletinfo, "inletinfo",

A_CANT, 0);

If all of your object's non-left inlets are "cold" you can use the function stdinletinfo() instead of writing your own, as
shown below:

class_addmethod(c, (method)stdinletinfo, "inletinfo",

A_CANT, 0);

To write your own function, just look at the index argument (which is 0 for the left inlet). This example turns the third
inlet cold. You don't need to do anything for "hot" inlets.

void myobject_inletinfo(t_myobject *x, void *b, long index, char *t)

{
if (index == 2)
*t = 1;
}

14.5 Showing a Text Editor

Objects such as coll and text display a text editor window when you double-click. Users can edit the contents of the
objects and save the updated data (or not). Here's how to do the same thing in your object.
First, if you want to support double-clicking on a non-UI object, you can respond to the dblclick message.

class_addmethod(c, (method)myobject_dblclick, "dblclick",

A_CANT, 0);

void myobject_dblclick(t_myobject *x)

{
// open editor here
}

You'll need to add a t_object pointer to your object's data structure to hold the editor.

typedef struct _myobject

{
t_object m_obj;
t_object *m_editor;
} t_myobject;

Initialize the m_editor field to NULL in your new instance routine. Then implement the dblclick method as follows:

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

14.5 Showing a Text Editor 61

if (!x->m_editor)
x->m_editor = object_new(CLASS_NOBOX, gensym("jed"), (
t_object *)x, 0);
else
object_attr_setchar(x->m_editor, gensym("visible"), 1);

The code above does the following: If the editor does not exist, we create one by making a "jed" object and passing
our object as an argument. This permits the editor to tell our object when the window is closed.
If the editor does exist, we set its visible attribute to 1, which brings the text editor window to the front.
To set the text of the edit window, we can send our jed object the settext message with a zero-terminated buffer of
text. We also provide a symbol specifying how the text is encoded. For best results, the text should be encoded as
UTF-8. Here is an example where we set a string to contain "Some text to edit" then pass it to the editor.

char text[512];

strcpy(text,"Some text to edit");

object_method(x->m_editor, gensym("settext"), text, gensym("utf-8"));

The title attribute sets the window title of the text editor.

object_attr_setsym(x->m_editor, gensym("title"), gensym("crazytext"));

When the user closes the text window, your object (or the object you passed as an argument when creating the
editor) will be sent the edclose message.

class_addmethod(c, (method)myobject_edclose, "edclose",

A_CANT, 0);

The edclose method is responsible for doing something with the text. It should also zero the reference to the editor
stored in the object, because it will be freed. A pointer to the text pointer is passed, along with its size. The encoding
of the text is always UTF-8.

void myobject_edclose(t_myobject *x, char **ht, long size)

{
// do something with the text
x->m_editor = NULL;
}

If your object will be showing the contents of a text file, you are still responsible for setting the initial text, but you can
assign a file so that the editor will save the text data when the user chooses Save from the File menu. To assign a
file, use the filename message, assuming you have a filename and path ID.

object_method(x->m_editor, gensym("filename"), x->m_myfilename, x->m_mypath);

The filename message will set the title of the text editor window, but you can use the title attribute to override the
simple filename. For example, you might want the name of your object to precede the filename:

char titlename[512];

sprintf(titlename, "myobject: %s", x->m_myfilename);

object_attr_setsym(x->m_editor, gensym("title"), gensym(titlename));

Each time the user chooses Save, your object will receive an edsave message. If you return zero from your edsave
method, the editor will proceed with saving the text in a file. If you return non-zero, the editor assumes you have
taken care of saving the text. The general idea is that when the user wants to save the text, it is either updated
inside your object, updated in a file, or both. As an example, the js object uses its edsave message to trigger a
recompile of the Javascript code. But it also returns 0 from its edsave method so that the text editor will update the
script file. Except for the return value, the prototype of the edsave method is identical to the edclose method.

class_addmethod(c, (method)myobject_edsave, "edsave",

A_CANT, 0);

long myobject_edsave(t_myobject *x, char **ht, long size)

{
// do something with the text
return 0; // tell editor it can save the text
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

62 Enhancements to Objects

14.6 Accessing Data in table Objects

Table objects can be given names as arguments. If a table object has a name, you can access the data using
table_get(). Supply a symbol, as well as a place to assign a pointer to the data and the length. The following
example accesses a table called foo, and, if found, posts all its values.

long **data = NULL;

long i, size;

if (!table_get(gensym("foo"), &data, &size)) {

for (i = 0; i < size; i++) {
post("%ld: %ld",i,(*data)[i]);
}
}

You can also write data into the table. If you would like the table editor to redraw after doing so, use table_dirty().
Here's an example where we set all values in the table to zero, then notify the table to redraw.

long **data = NULL;

long i, size;

if (!table_get(gensym("foo"), &data, &size)) {

for (i = 0; i < size; i++) {
(*data)[i] = 0;
}
table_dirty(gensym("foo"));
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 15

Data Structures

15.1 Available Data Structures

The Max API provides a variety of useful data structures which may be used across platforms and provide basic
thread-safety.

• Atom Array : container for an array of atoms

• Linked List : doubly-linked-list

• Hash Table : hash table for mapping symbols to data

• Quick Map : a double hash with keys mapped to values and vice-versa

• Database : SQLite database access

• Index Map : managed array of pointers

• String Object : wrapper for C-strings with an API for manipulating them

• Symbol Object : wrapper for symbols

• Dictionary : structured/hierarchical data that is both sortable and fast

15.2 Passing Data Structures

Most often, the use of a particular instance of a data structure will be limited to within the confines a single class or
object you create. However, in some cases you may wish to pass structured data from one object to another. For
this purpose, Max 6 introduced facilities for passing named t_dictionary instances.
Examples, descriptions, and API documentation can be found in Dictionary Passing API .
64 Data Structures

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 16

Threading

The Max systhread API has two main purposes.

First, it can be used to implement thread protection which works in conjunction with Max's existing threading model
and is cross-platform. Thread protection prevents data corruption in the case of simultaneously executing threads in
the same application. We'll discuss the Max threading model and show you a simple example of thread protection
below, but you can often avoid the need to use thread protection by using one of the thread-safe Data Storage Max
provides.
The second use of the systhread API is a cross-platform way to create and manage threads. This is an advanced
feature that very few programmers will ever need. For information on creating and managing threads look at the
systhread API header file.

16.1 Max Threading Operation

Please note that this description of how Max operates is subject to change and may not apply to future versions.
For more information about the Max scheduler and low-priority queue, see the The Scheduler section.
Max (without audio) has two threads. The main or event thread handles user interaction, asks the system to redraw
the screen, processes events in the low-priority queue. When not in Overdrive mode, the main thread handles the
execution of events in the Max scheduler as well. When Overdrive is enabled, the scheduler is moved to a high-
priority timer thread that, within performance limits imposed by the operating system, attempts to run at the precise
scheduler interval set by user preference. This is usually 1 or 2 milliseconds.
The basic idea is to put actions that require precise timing and are relatively computationally cheap in the high-
priority thread and computationally expensive events that do not require precise timing in the main thread. On
multi-core machines, the high-priority thread may (or may not) be executing on a different core.
On both Mac and Windows, either the main thread or the timer thread can interrupt the other thread, even though
the system priority level of the timer thread is generally much higher. This might seem less than optimal, but it is
just how operating systems work. For example, if the OS comes to believe the Max timer thread is taking too much
time, the OS may "punish" the thread by interrupting it with other threads, even if those threads have a lower system
priority.
Because either thread can be interrupted by the other, it is necessary to use thread protection to preserve the
integrity of certain types of data structures and logical operations. A good example is a linked list, which can be
corrupted if a thread in the process of modifying the list is interrupted by another thread that tries to modify the list.
The Max t_linklist data structure is designed to be thread-safe, so if you need such a data structure, we suggest you
use t_linklist. In addition, Max provides thread protection between the timer thread and the main thread for many of
its common operations, such as sending messages and using outlets.
When we add audio into the mix (so to speak), the threading picture gets more complicated. The audio perform
routine is run inside a thread that is controlled by the audio hardware driver. In order to eliminate excessive thread
blocking and potential race conditions, the thread protection offered inside the audio perform routine is far less
comprehensive, and as discussed in the MSP section of the API documentation, the only supported operation for
66 Threading

perform routines to communicate to Max is to use a clock. This will trigger a function to run inside the Max scheduler.
The Max scheduler can be run in many different threading conditions. As explained above it can be run either in the
main thread or the timer thread. When Scheduler in Audio Interrupt (SIAI) is enabled, the scheduler runs with an
interval equal to every signal vector of audio inside the audio thread. However, if the Non-Real-Time audio driver is
used, the audio thread is run inside the main thread, and if SIAI is enabled, the scheduler will also run inside the
main thread. If not, it will run either in the main thread or the timer thread depending on the Overdrive setting. (Using
the Non-Real-Time audio driver without SIAI will generally lead to unpredictable results and is not recommended.)

16.2 Thread Protection

The easiest method for thread protection is to use critical sections. A critical section represents a region of code that
cannot be interrupted by another thread. We speak of entering and exiting a critical section, and use critical_enter()
and critical_exit() to do so.
Max provides a default global critical section for your use. This same critical section is used to protect the timer
thread from the main thread (and vice versa) for many common Max data structures such as outlets. If you call
critical_enter() and critical_exit() with argument of 0, you are using this global critical section. Typically it is more
efficient to use fewer critical sections, so for many uses, the global critical section is sufficient. Note that the critical
section is recursive, so you if you exit the critical section from within some code that is already protected, you won't
be causing any trouble.

16.2.1 When Messages Arrive

It's possible that a message sent to your object could interrupt the same message sent to your object ("myobject").
For example, consider what happens when a button is connected to the left inlet of myobject and a metro connected
to the same inlet.
When a user clicks on the bang button, the message is sent to your object in the main thread. When Overdrive is
enabled, the metro will send a bang message to your object in the timer thread. Either could interrupt the other. If
your object performs operations on a data structure that cannot be interrupted, you should use thread protection.

16.2.2 Critical Section Example

Here is an example that uses the global critical section to provide thread protection for an array data structure.
Assume we have an operation array_read() that reads data from an array, and array_insert() that inserts data into
the same array. We wish to ensure that reading doesn't interrupt writing and vice versa.

long array_read(t_myobject *x, long index)

{
critical_enter(0);
result = x->m_data[index];
critical_exit(0);
return result;
}

Note that all paths of your code must exit the critical region once it is entered, or the other threads in Max will never
execute.

long array_insert(t_myobject *x, long index, long value)

{
critical_enter(0);
// move existing data
sysmem_copyptr(x->m_data + index, x->m_data + index + 1, (x->m_size - x->m_index) *
sizeof(long));
// write new data
x->m_data[index] = value;
critical_exit(0);
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 17

Drag'n'Drop

The Max file browser permits you to drag files to a patcher window or onto objects to perform file operations.
Your object can specify the file types accepted as well as a message that will be sent when the user releases the
mouse button with the file on top of the object. UI and non-UI objects use the same interface to drag'n'drop.
Example UI object: pictmeter∼. Example non-UI: TBD.
Messages to support:

acceptsdrag_locked (A_CANT)

Sent to an object during a drag when the mouse is over the object in an unlocked patcher.

acceptsdrag_unlocked (A_CANT)

Sent to an object during a drag when the mouse is over the object in a locked patcher.

17.1 Discussion

Why two different scenarios? acceptsdrag_unlocked() can be thought of as an "editing" operation. For example,
objects such as pictslider accept new image files for changing their appearance when the patcher is unlocked, but
not when the patcher is locked. By contrast, sfplay∼ can accept audio files for playback in either locked or unlocked
patchers, since that is something you can do with a message (rather than an editing operation that changes the
patcher).
Message handler definitions:

long myobject_acceptsdrag_unlocked(t_myobject *x, t_object *drag,

t_object *view);
long myobject_acceptsdrag_locked(t_myobject *x, t_object *drag, t_object *view);

The handlers return true if the file(s) contained in the drag can be used in some way by the object. To test the
filetypes, use jdrag_matchdragrole() passing in the drag object and a symbol for the file type. Here is list of pre-
defined file types:

• audiofile

• imagefile

• moviefile

• patcher

• helpfile
68 Drag'n'Drop

• textfile

or to accept all files, use file

If jdrag_matchdragrole() returns true, you then describe the messages your object receives when the drag com-
pletes using jdrag_object_add(). You can add as many messages as you wish. If you are only adding a single
message, use jdrag_object_add(). For more control over the process, and for adding more than one message,
jdrag_add() can be used. If you add more than one message, the user can use the option key to specify the desired
action. By default, the first one you add is used. If there are two actions, the option key will cause the second one
to be picked. If there are more than two, a pop-up menu appears with descriptions of the actions (as passed to
jdrag_add()), and the selected action is used.
Example:
This code shows how to respond to an audiofile being dropped on your object by having the read message sent.

if (jdrag_matchdragrole(drag, gensym("audiofile"), 0)) {

jdrag_object_add(drag, (t_object *)x, gensym("read"));
return true;
}
return false;

Your acceptsdrag handler can test for multiple types of files and add different messages.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 18

ITM

ITM is the tempo-based timing system introduced with Max 5.

It allows users to express time in tempo-relative units as well as milliseconds, samples, and an ISO 8601 hour-
minute-second format. In addition, ITM supports one or more transports, which can be synchronized to external
sources. An ITM-aware object can schedule events to occur when the transport reaches a specific time, or find out
the current transport state.
The ITM API is provided on two different levels. The time object (t_timeobject) interface provides a higher-level way
to parse time format information and schedule events. In addition, you can use lower-level routines to access ITM
objects (t_itm) directly. An ITM object is responsible for maintaining the current time and scheduling events. There
can be multiple ITM objects in Max, each running independently of the others.

18.1 Scheduling Temporary Events

There are two kinds of events in ITM. Temporary events are analogous to Max clock objects in that they are sched-
uled and fire at a dynamically assigned time. Once they have executed, they are removed from the scheduler.
Permanent events always fire when the transport reaches a specific time, and are not removed from the sched-
uler. The ITM-aware metro is an example of an object that uses temporary events, while the timepoint object uses
permanent events. We'll show how to work both types using an example included in the SDK called delay2. The
existing Max delay object provides this capability, but this example shows most of the things you can do with the
time object interface. To see the complete object, look at the delay2 example. We'll introduce a simpler version of
the object, then proceed to add the quantization and the additional outlet that generates a delayed bang based on
low-level ITM calls.
The ITM time object API is based on a Max object you create that packages up common ways you will be using
ITM, including attribute support, quantization, and, if you want it, the ability to switch between traditional millisecond-
based timing and tempo-based timing using an interface that is consistent with the existing Max objects such as
metro and delay. (If you haven't familiarized yourself with attributes, you may want to read through the discussion
about them in Attributes before reading further.)
To use the time object, you'll first need to provide some space in your object to hold a pointer to the object(s) you'll
be creating.

typedef struct _delay2simple

{
t_object m_ob;
t_object *m_timeobj;
void *m_outlet;
} _delay2simple;

Next, in your ext_main() routine, you'll create attributes associated with the time object using the class_time_←-
addattr() function.

class_time_addattr(c, "delaytime", "Delay Time",

TIME_FLAGS_TICKSONLY | TIME_FLAGS_USECLOCK |
TIME_FLAGS_TRANSPORT);
70 ITM

The second argument, "delaytime", is a string that names the attribute. Users of your object will be able to change
the delay value by sending a delaytime message. "Delay Time" is the label users see for the attribute in the inspector.
The flags argument permits you to customize the type of time object you'd like. TIME_FLAGS_TICKSONLY means
that the object can only be specified in tempo-relative units. You would not use this flag if you want the object to use
the regular Max scheduler if the user specifies an absolute time (such as milliseconds). TIME_FLAGS_USECLOCK
means that it is a time object that will actually schedule events. If you do not use this flag, you can use the time
object to hold and convert time values, which you use to schedule events manually. TIME_FLAGS_TRANSPO←-
RT means that an additional attribute for specifying the transport name is added to your object automatically (it's
called "transport" and has the label "Transport Name"). The combination of flags above is appropriate for an object
that will be scheduling events on a temporary basis that are only synchronized with the transport and specified in
tempo-relative units.
The next step is to create a time object in your new instance routine using time_new. The time_new function is
something like clock_new – you pass it a task function that will be executed when the scheduler reaches a certain
time (in this case, delay2simple_tick, which will send out a bang). The first argument to time_new is a pointer to
your object, the second is the name of the attribute created via class_time_addattr, the third is your task function,
and the fourth are flags to control the behavior of the time object, as explained above for class_time_addattr.
Finally, we use time_setvalue to set the initial delay value to 0.

void *delay2simple_new()
{
t_delay2simple *x;
t_atom a;

x = (t_delay2simple *)object_alloc(s_delay2simple_class);
x->m_timeobj = (t_object *)time_new((t_object *)x,
gensym("delaytime"), (method)delay2simple_tick, TIME_FLAGS_TICKSONLY |
TIME_FLAGS_USECLOCK);
x->m_outlet = bangout((t_object *)x);
atom_setfloat(&a, 0.);
time_setvalue(x->d_timeobj, NULL, 1, &a);
return x;
}

To make a delayed bang, we need a delay2simple_bang function that causes our time object to put its task func-
tion into the ITM scheduler. This is accomplished using time_schedule. Note that unlike the roughly equivalent
clock_fdelay, where the delay time is an argument, the time value must already be stored inside the time object
using time_setvalue. The second argument to time_schedule is another time object that can be used to control
quantization of an event. Since we aren't using quantization in this simple version of delay2, we pass NULL.

void delay2simple_bang(t_delay2 *x)

{
time_schedule(x->d_timeobj, NULL);
}

Next, our simple task routine, delay2simple_tick. After the specified number of ticks in the time object has elapsed
after the call to time_schedule, the task routine will be executed.

void delay2_tick(t_delay2 *x)

{
outlet_bang(x->d_outlet);
}

Now let's add the two more advanced features found in delay2: quantization and a second (unquantized) bang
output using low-level ITM routines. Here is the delay2 data structure. The new elements are a proxy (for receiving
a delay time), a time object for quantization (d_quantize), a clock to be used for low-level ITM scheduling, and an
outlet for the use of the low-level clock's task.

typedef struct delay2

{
t_object d_obj;
void *d_outlet;
void *d_proxy;
long d_inletnum;
t_object *d_timeobj;
t_object *d_outlet2;
t_object *d_quantize;
void *d_clock;
} t_delay2;

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

18.2 Permanent Events 71

In the initialization routine, we'll define a quantization time attribute to work in conjunction with the d_quantize time
object we'll be creating. This attribute does not have its own clock to worry about. It just holds a time value, which
we specify will only be in ticks (quantizing in milliseconds doesn't make sense in the ITM context). If you build delay2
and open the inspector, you will see time attributes for both Delay Time and Quantization.

class_time_addattr(c, "quantize", "Quantization",

TIME_FLAGS_TICKSONLY);

Here is part of the revised delay2 new instance routine. It now creates two time objects, plus a regular clock object.

x->d_inletnum = 0;
x->d_proxy = proxy_new(x, 1, &x->d_inletnum);
x->d_outlet2 = bangout(x);
x->d_outlet = bangout(x);

x->d_timeobj = (t_object*) time_new((t_object *)x,

gensym("delaytime"), (method)delay2_tick, TIME_FLAGS_TICKSONLY |
TIME_FLAGS_USECLOCK);
x->d_quantize = (t_object*) time_new((t_object *)x,
gensym("quantize"), NULL, TIME_FLAGS_TICKSONLY);
x->d_clock = clock_new((t_object *)x, (method)delay2_clocktick);

To use the quantization time object, we can pass it as the second argument to time_schedule. If the value of the
quantization is 0, there is no effect. Otherwise, time_schedule will move the event time so it lies on a quantization
boundary. For example, if the quantization value is 4n (480 ticks), the delay time is 8n (240 ticks) and current time
is 650 ticks, the delay time will be adjusted so that the bang comes out of the delay2 object at 980 ticks instead of
890 ticks.
In addition to using quantization with time_schedule, delay2_bang shows how to calculate a millisecond equivalent
for an ITM time value using itm_tickstoms. This delay value is not quantized, although you read the time value from
the d_quantize object and calculate your own quantized delay if wanted. The "calculated" delay is sent out the right
outlet, since the clock we created uses delay2_clocktick.

void delay2_bang(t_delay2 *x)

{
double ms, tix;

time_schedule(x->d_timeobj, x->d_quantize);

tix = time_getticks(x->d_timeobj);
tix += (tix / 2);
ms = itm_tickstoms(time_getitm(x->d_timeobj), tix);
clock_fdelay(x->d_clock, ms);
}

void delay2_clocktick(t_delay2 *x)

{
outlet_bang(x->d_outlet2);
}

18.2 Permanent Events

A permanent event in ITM is one that has been scheduled to occur when the transport reaches a specific time. You
can schedule a permanent event in terms of ticks or bars/beats/units. An event based in ticks will occur when the
transport reaches the specified tick value, and it will not be affected by changes in time signature. An event specified
for a time in bars/beats/units will be affected by the time signature. As an example, consider an event scheduled
for bar 2, beat 1, unit 0. If the time signature of the ITM object on which the event has been scheduled is 3/4, the
event will occur at 480 times 3 or 1440 ticks. But if the time signature is 4/4, the event will occur at 1920 ticks. If, as
an alternative, you had scheduled the event to occur at 1920 ticks, setting the time signature to 3/4 would not have
affected when it occurred.
You don't "schedule" a permanent event. Once it is created, it is always in an ITM object's list of permanent events.
To specify when the event should occur, use time_setvalue.
The high-level time object interface handles permanent events. Let's say we want to have a time value called
"targettime." First, we declare an attribute using class_time_addattr. The flags used are TIME_FLAGS_TICKS←-
ONLY (required because you can't specify a permanent event in milliseconds), TIME_FLAGS_LOCATION (which

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

72 ITM

interprets the bar/beat/unit times where 1 1 0 is zero ticks), TIME_FLAGS_PERMANENT (for a permanent event),
and TIME_FLAGS_TRANSPORT (which adds a transport attribute permitting a user to choose a transport object
as a destination for the event) and TIME_FLAGS_POSITIVE (constrains the event to happen only for positive tick
and bar/beat/unit values).

class_time_addattr(c, "targettime", "Target Time",

TIME_FLAGS_TICKSONLY | TIME_FLAGS_LOCATION |
TIME_FLAGS_PERMANENT | TIME_FLAGS_TRANSPORT |
TIME_FLAGS_POSITIVE);

The TIME_FLAGS_TRANSPORT flag is particularly nice. Without any intervention on your part, it creates a trans-
port attribute for your object, and takes care of scheduling the permanent event on the transport the user specifies,
with a default value of the global ITM object. If you want to cause your event to be rescheduled dynamically when
the user changes the transport, your object can respond to the reschedule message as follows.

class_addmethod(c, (method)myobject_reschedule, "reschedule",

A_CANT, 0); // for dynamic transport reassignment

All you need to do in your reschedule method is just act as if the user has changed the time value, and use the
current time value to call time_setvalue.
In your new instance routine, creating a permanent event with time_new uses the same flags as were passed to
class_time_addattr:

x->t_time = (t_object*) time_new((t_object *)x, gensym("targettime"), (

method)myobject_tick, TIME_FLAGS_TICKSONLY |
TIME_FLAGS_USECLOCK | TIME_FLAGS_PERMANENT |
TIME_FLAGS_LOCATION | TIME_FLAGS_POSITIVE);

The task called by the permanent time object is identical to a clock task or an ITM temporary event task.

18.3 Cleaning Up

With all time objects, both permanent and temporary, it's necessary to free the objects in your object's free method.
Failure to do so will lead to crashes if your object is freed but its events remain in the ITM scheduler. For example,
here is the delay2 free routine:

void delay2_free(t_delay2 *x)

{
freeobject(x->d_timeobj);
freeobject(x->d_quantize);
freeobject((t_object *) x->d_proxy);
freeobject((t_object *)x->d_clock);
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 19

Jitter Object Model

19.1 Jitter Object Model Basics

Jitter objects use an object model which is somewhat different than the one traditionally used for developing Max
external objects. The first big difference between Jitter objects and traditional Max external objects is that Jitter
objects don't have any notion of the patcher themselves. This allows for the flexible instantiation and use of Jitter
objects from C, Java, JavaScript, as well as in the Max patcher. The use of these Jitter objects is exposed to the
patcher with a Max "wrapper" object, which will be discussed in the following chapter.
In this chapter we'll restrict our discussion to the fundamentals of defining the Jitter object which can be used in
any of these languages. While Jitter's primary focus is matrix processing and real-time graphics, these tasks are
unrelated to the object model, and will be covered in later chapters on developing Matrix Operator (MOP) and OB3D
objects. Like Max objects, Jitter objects are typically written in C. While C++ can be used to develop Jitter objects,
none of the object oriented language features will be used to define your object as far as Jitter is concerned. Similar
to C++ or Java objects, Jitter objects are defined by a class with methods and member variables - we will refer to the
member variables as "attributes". Unlike C++ or Java, there are no language facilities that manage class definition,
class inheritance, or making use of class instances. In Jitter this must all be managed with sets of standard C
function calls that will define your class, exercise methods, and get and set object attributes.
Max and Jitter implement their object models by maintaining a registry of ordinary C functions and struct members
that map to methods and attributes associated with names. When some other code wishes to make use of these
methods or attributes, it asks the Jitter object to look up the method or attribute in its registry based on a name.
This is called dynamic binding, and is similar to Smalltalk or Objective C's object model. C++ and Java typically
make use of static binding — i.e. methods and member variables are resolved at compile time rather than being
dynamically looked up at run time.

19.2 Defining a Jitter Class

A Jitter class is typically defined in a C function named something like your_object_name_init(). Class definition
begins with a call to jit_class_new(), which creates a new class associated with a specified name, constructor,
destructor, and size in bytes of the object as stored in a C structure. This is followed by calls to jit_class_←-
addmethod() and jit_class_addattr(), which register methods and attributes with their corresponding names in the
class. The class is finally registered with a call to jit_class_register(). A minimal example class definition is shown
below:

typedef struct _jit_foo

{
t_jit_object ob;
float myval;
} t_jit_foo;

static t_jit_class *_jit_foo_class=NULL;

t_jit_err jit_foo_init(void)
{
74 Jitter Object Model

long attrflags=0;
t_jit_object *attr;

// create new class named "jit_foo" with constructor + destructor

_jit_foo_class = jit_class_new("jit_foo",(method)jit_foo_new,
(method)jit_foo_free, sizeof(t_jit_foo), 0L);

// add method to class

jit_class_addmethod(jit_foo_scream, "scream", A_DEFLONG, 0L);

// define attribute
attr = jit_object_new( // instantiate an object
_jit_sym_jit_attr_offset, // of class jit_attr_offset
"myval", // with name "myval"
_jit_sym_float32, // type float32
attrflags, // default flags
(method)0L, // default getter accessor
(method)0L, // default setter accessor
calcoffset(t_jit_foo,myval)); // byte offset to struct member

// add attribute object to class

jit_class_addattr(_jit_foo_class, attr);

// register class
jit_class_register(_jit_foo_class);

return JIT_ERR_NONE;
}

// constructor
t_jit_foo *jit_foo_new(void)
{
t_jit_foo *x;

// allocate object
if (x=jit_object_alloc(_jit_foo_class))
{
// if successful, perform any initialization
x->myval = 0;
}
return x;
}

// destructor
void jit_foo_free(t_jit_foo *x)
{
// would free any necessary resources here
}

// scream method
void jit_foo_scream(t_jit_foo *x, long i)
{
post("MY VALUE IS %f! AND MY ARGUMENT IS %d", x->myval, i);
}

The above example has a constructor, jit_foo_new(); a destructor, jit_foo_free(); one 32 bit floating point attribute,
myval, a member of the object struct accessed with default accessor methods; and a method jit_foo_scream(),
which posts the current value of myval to the Max window.

19.3 Object Struct

Each instance of an object occupies some region of organized memory. The C structure that defines this organiza-
tion of memory is typically referred to as the "object struct". It is important that the object struct always begin with
an entry of type t_jit_object. It is within the t_jit_object where special information about the class is kept. The C
structure can contain additional information, either exposed as attributes or not, but it is important that the size of
the object struct does not exceed 16384 bytes. This means that it is not safe to define a large array as a struct entry
if it will cause the size of the object struct to be larger than this limit. If additional memory is required, the object
struct should contain a pointer to memory allocated from within the constructor, and freed within the destructor.
The class registration in the above code makes use of the object struct both to record in the class how large
each object instance should be—i.e. sizeof(t_jit_foo) ; and at what byte offset in the object struct an attribute is
located—i.e. calcoffset(t_jit_foo, myval) . When methods of an object are called, the instance of the object struct is
passed as the first argument to the C functions which define the object methods. This instance may be thought of
as similar to the "this" keyword used in C++ and Java - actually the C++ and Java underlying implementation works
quite similarly to what has been implemented here in pure C. Object struct entries may be thought of as similar to

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

19.4 Constructor/Destructor 75

object member variables, but methods must be called via functions rather than simply dereferencing instances of
the class as you might do in C++ or Java. The list of object methods and other class information is referenced by
your object's t_jit_object entry.

19.4 Constructor/Destructor

The two most important methods that are required for all objects are the constructor and the destructor. These
are typically named your_object_name_new(), and your_object_name_free(), respectively. It is the constructor's
responsibility to allocate and initialize the object struct and any additional resources the object instance requires.
The object struct is allocated via jit_object_alloc(), which also initializes the t_jit_object struct entry to point at your
relevant class information. The class information resides in your global class variable, e.g. _jit_foo_class, which you
pass as an argument to jit_object_alloc(). This allocation does not, however initialize the other struct entries, such
as "myval", which you must explicitly initialize if your allocation is successful. Note that because the constructor
allocates the object instance, no object instance is passed as the first argument to the function which defines the
constructor, unlike other object methods.
The constructor also has the option of having a typed argument signature with the same types as defined in the
Writing Max Externals documentation—i.e. A_LONG, A_FLOAT, A_SYM, A_GIMME, etc. Typically, Jitter object
constructors either have no arguments or use the A_GIMME typed argument signature.
In earlier versions of Jitter, the constructors were often specified as private and "untyped" using the A_CANT type
signature. While this obsolete style of an untyped constructor will work for the exposure of a Jitter class to the
patcher and C, it is now discouraged, as there must be a valid type signature for exposure of a class to Javascript
or Java, though that signature may be the empty list.
It is the destructor's responsibility to free any resources allocated, with the exception of the object struct itself. The
object struct is freed for you after your destructor exits.

19.5 Methods

You can define additional methods using the jit_class_addmethod() function. This example defines the scream
method associated with the function jit_foo_scream(), with no additional arguments aside from the standard first
argument of a pointer to the object struct. Just like methods for ordinary Max objects, these methods could have
a typed argument signature with the same types as defined in the Writing Max Externals documentation — i.←-
e. A_LONG, A_FLOAT, A_SYM, A_GIMME. Typically in Jitter objects, public methods are specified either without
arguments, or use A_GIMME, or the low priority variants, A_DEFER_LOW, or A_USURP_LOW, which will be
discussed in following chapters. Private methods, just like their Max equivalent should be defined as untyped, using
the A_CANT type signature. Object methods can be called from C either by calling the C function directly, or by
using jit_object_method() or jit_object_method_typed(). For example, the following calls that relate to the above
jit_foo example are equivalent:

// call scream method directly

jit_foo_scream(x, 74);

// dynamically resolve and call scream method

jit_object_method(x, gensym("scream"), 74);

// dynamically resolve and call scream method with typed atom arguments
t_atom a[1];
jit_atom_setlong(a, 74);
jit_object_method_typed(x, gensym("scream"), 1, a, NULL);

What the jit_object_method() and jit_object_method_typed() functions do is look up the provided method symbol in
the object's class information, and then calls the corresponding C function associated with the provided symbol. The
difference between jit_object_method() and jit_object_method_typed() is that jit_object_method() will not require
that the method is typed and public, and blindly pass all of the arguments following the method symbol on to the
corresponding method. For this reason, it is required that you know the signature of the method you are calling,
and pass the correct arguments. This is not type checked at compile time, so you must be extremely attentive to
the arguments you pass via jit_object_method(). It is also possible for you to define methods which have a typed

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

76 Jitter Object Model

return value with the A_GIMMEBACK type signature. When calling such methods, the final argument to jit_object←-
_method_typed(), should point to a t_atom to be filled in by the callee. This and the subject of "typed wrappers" for
exposing otherwise private methods to language bindings that require typed methods (e.g. Java/!JavaScript) will be
covered in a later chapter.

19.6 Attributes

You can add attributes to the class with jit_class_addattr(). Attributes themselves are Jitter objects which share a
common interface for getting and setting values. While any class which conforms to the attribute interface could be
used to define attributes of a given class, there are a few common classes which are currently used: jit_attr_offset(),
which specifies a scalar attribute of a specific type (char, long, float32, float64, symbol, or atom) at some byte offset
in the object struct; jit_attr_offset_array() which specifies an array (vector) attribute of a specific type (char, long,
float32, float64, symbol, or atom) at some byte offset in the object struct; and jit_attribute, which is a more generic
attribute object that can be instantiated on a per object basis. We will not document the usage of jit_attribute at this
time. The constructor for the class jit_attr_offset() has the following prototype:

t_jit_object *jit_attr_offset_new(char *name,

t_symbol *type, long flags,
method mget, method mset, long offset);

When this constructor is called via jit_object_new(), additionally the class name, _jit_sym_jit_attr_offset (a global
variable equivalent to gensym("jit_attr_offset") ) must be passed as the first parameter, followed by the above argu-
ments, which are passed on to the constructor. The name argument specifies the attribute name as a null terminated
C string. The type argument specifies the attribute type, which may be one of the following symbols: _jit_sym_char,
_jit_sym_long, _jit_sym_float32, _jit_sym_float64, _jit_sym_symbol, _jit_sym_atom, _jit_sym_object, or _jit_sym←-
_pointer. The latter two are only useful for private attributes as these types are not exposed to, or converted from
Max message atom values.
The flags argument specifies the attribute flags, which may be a bitwise combination of the following constants:

#define JIT_ATTR_GET_OPAQUE 0x00000001 // cannot query

#define JIT_ATTR_SET_OPAQUE 0x00000002 // cannot set
#define JIT_ATTR_GET_OPAQUE_USER 0x00000100 // user cannot query
#define JIT_ATTR_SET_OPAQUE_USER 0x00000200 // user cannot set
#define JIT_ATTR_GET_DEFER 0x00010000 // (deprecated)
#define JIT_ATTR_GET_USURP 0x00020000 // (deprecated)
#define JIT_ATTR_GET_DEFER_LOW 0x00040000 // query in low priority
#define JIT_ATTR_GET_USURP_LOW 0x00080000 // query in low, usurping
#define JIT_ATTR_SET_DEFER 0x01000000 // (deprecated)
#define JIT_ATTR_SET_USURP 0x02000000 // (deprecated)
#define JIT_ATTR_SET_DEFER_LOW 0x04000000 // set at low priority
#define JIT_ATTR_SET_USURP_LOW 0x08000000 // set at low, usurping

Typically attributes in Jitter are defined with flags JIT_ATTR_GET_DEFER_LOW, and JIT_ATTR_SET_USURP←-
_LOW. This means that multiple queries from the patcher will generate a response for each query, and that multiple
attempts to set the value at high priority will collapse into a single call with the last received value. For more
information on defer and usurp, see the chapter on Jitter scheduling issues.
The mget argument specifies the attribute "getter" accessor method, used to query the attribute value. If this
argument is zero (NULL), then the default getter accessor will be used. If you need to define a custom accessor, it
should have a prototype and form comparable to the following custom getter:

t_jit_err jit_foo_myval_get(t_jit_foo *x, void *attr, long *ac, t_atom **av)

{
if ((*ac)&&(*av)) {
//memory passed in, use it
} else {
//otherwise allocate memory
*ac = 1;
if (!(*av = jit_getbytes(sizeof(t_atom)*(*ac)))) {
*ac = 0;
return JIT_ERR_OUT_OF_MEM;
}
}
jit_atom_setfloat(*av,x->myval);

return JIT_ERR_NONE;
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

19.7 Array Attributes 77

Note that getters require memory to be allocated, if there is not memory passed into the getter. Also the attr
argument is the class' attribute object and can be queried using jit_object_method() for things like the attribute flags,
names, filters, etc.. The mset argument specifies the attribute "setter" accessor method, used to set the attribute
value. If this argument is zero (NULL), then the default setter accessor will be used. If we need to define a custom
accessor, it should have a prototype and form comparable to the following custom setter:

t_jit_err jit_foo_myval_set(t_jit_foo *x, void *attr, long ac, t_atom *av)

{
if (ac&&av) {
x->myval = jit_atom_getfloat(av);
} else {
// no args, set to zero
x->myval = 0;
}
return JIT_ERR_NONE;
}

The offset argument specifies the attribute's byte offset in the object struct, used by default getters and setters to
automatically query and set the attribute's value. If you have both custom accessors, this value is ignored. This can
be a useful strategy to employ if you wish to have an object attribute that does not correspond to any actual entry
in your object struct. For example, this is how we implement the time attribute of jit.movie — i.e. it uses a custom
getter and setter which make QuickTime API calls to query and set the current movie time, rather than manipulating
the object struct itself, where no information about movie time is actually stored. In such an instance, you should
set this offset to zero.
After creating the attribute, it must be added to the Jitter class using the jit_class_addattr() function:

t_jit_err jit_class_addattr(void *c, t_jit_object *attr);

To put it all together: to define a jit_attribute_offset() with the custom getter and setter functions defined above, you'd
make the following call:

long attrflags = JIT_ATTR_GET_DEFER_LOW |

JIT_ATTR_SET_USURP_LOW;
t_jit_object *attr = jit_object_new(_jit_sym_jit_attr_offset, "myval",
_jit_sym_float32, attrflags,
(method)jit_foo_myval_get, (method)jit_foo_myval_set, NULL);
jit_class_addattr(_jit_foo_class, attr);

And to define a completely standard jit_attribute_offset(), using the default getter and setter methods:

long attrflags = JIT_ATTR_GET_DEFER_LOW |

JIT_ATTR_SET_USURP_LOW;
t_jit_object *attr = jit_object_new(_jit_sym_jit_attr_offset, "myval",
_jit_sym_float32, attrflags,
(method)NULL, (method)NULL, calcoffset(t_jit_foo, myval));
jit_class_addattr(_jit_foo_class, attr);

19.7 Array Attributes

Attributes can, in addition to referencing single values, also refer to arrays of data. The class jit_attribute_offset_←-
array is used in this instance. The constructor for the class jit_attr_offset_array() has the following prototype:

t_jit_object *jit_attr_offset_array_new(char *name,

t_symbol *type, long size,
long flags, method mget, method mset, long offsetcount, long offset);

When this constructor is called via jit_object_new(), additionally the class name, _jit_sym_jit_attr_offset_array() (a
global variable equivalent to gensym("jit_attr_offset_array") ) must be passed as the first parameter, followed by the
above arguments, which are passed on to the constructor.
The name, type, flags, mget, mset and offset arguments are identical to those specified above.
The size argument specifies the maximum length of the array (the allocated size of the array in the Jitter object
struct). The offsetcount specifies the byte offset in the object struct, where the actual length of the array can be

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

78 Jitter Object Model

queried/set. This value should be specified as a long. This value is used by default getters and setters when
querying and setting the attribute's value. As with the jit_attr_offset object, if you have both custom accessors, this
value is ignored.
The following sample listing demonstrates the creation of a simple instance of the jit_attr_offset_array() class for an
object defined as:

typedef struct _jit_foo

{
t_jit_object ob;
long myarray[10]; // max of 10 entries in this array
long myarraycount; // actual number being used
} t_jit_foo;

long attrflags = JIT_ATTR_GET_DEFER_LOW |

JIT_ATTR_SET_USURP_LOW;
t_jit_object *attr = jit_object_new(_jit_sym_jit_attr_offset_array
, "myarray",
_jit_sym_long, 10, attrflags, (method)0L, (method)0L,
calcoffset(t_jit_foo, myarraycount), calcoffset(t_jit_foo, myarray));
jit_class_addattr(_jit_foo_class, attr);

19.8 Attribute Notification

Although the subject of object registration and notification will be covered in greater depth in a forthcoming chapter,
it bears noting that attributes of all types (e.g. jit_attr_offset, jit_attr_offset_array and jit_attribute) will, if registered,
automatically send notifications to all attached client objects, each time the attribute's value is set.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 20

Jitter Max Wrappers

20.1 Max Wrapper Classes

In order to expose the Jitter object to the Max patcher, a Max "wrapper" class must be defined. For simple classes,
this is largely facilitated by a handful of utility functions that take a Jitter class and create the appropriate wrapper
class with default functionality. However, there are occasions which warrant additional intervention to achieve special
behavior, such as the use of additional inlets and outlets, integrating with MSP, converting matrix information to and
from Max lists, etc. The first Max wrapper class we'll demonstrate won't have any extra complication beyond simply
containing a basic Jitter class.
In general it is preferable to design the Jitter class so that it knows nothing about the Max patcher, and that any logic
necessary to communicate with the patcher is maintained in the Max wrapper class. In situations where this might
seem difficult, this can typically be accomplished by making special methods in the Jitter class that are only meant
to be called by the Max wrapper, or by using Jitter's object notification mechanism, which we'll discuss in a future
chapter. Below is the minimal Max wrapper class for the minimal Jitter class shown in the last chapter.

typedef struct _max_jit_foo

{
t_object ob;
void *obex;
} t_max_jit_foo;

void *class_max_jit_foo;

void ext_main(void *r)

{
void *p,*q;

// initialize the Jitter class

jit_foo_init();

// create the Max class as documented in Writing Max Externals

setup(&class_max_jit_foo,
(method) max_jit_foo_new,
(method) max_jit_foo_free,
(short)sizeof(t_max_jit_foo),
0L, A_GIMME, 0);

// specify a byte offset to keep additional information

p = max_jit_classex_setup(calcoffset(t_max_jit_foo, obex));

// look up the Jitter class in the class registry

q = jit_class_findbyname(gensym("jit_foo"));

// wrap the Jitter class with the standard methods for Jitter objects
max_jit_classex_standard_wrap(p, q, 0);

// add an inlet/outlet assistance method

addmess((method)max_jit_foo_assist, "assist", A_CANT,0);
}

void max_jit_foo_assist(t_max_jit_foo *x, void *b, long m, long a, char *s)

{
// no inlet/outlet assistance
}
80 Jitter Max Wrappers

void max_jit_foo_free(t_max_jit_foo *x)

{
// lookup the internal Jitter object instance and free
jit_object_free(max_jit_obex_jitob_get(x));

// free resources associated with the obex entry

max_jit_obex_free(x);
}

void *max_jit_foo_new(t_symbol *s, long argc, t_atom *argv)

{
t_max_jit_foo *x;
long attrstart;
void *o;

// create the wrapper object instance based on the

// max wrapper class, and the jitter class
if (x = (t_max_jit_foo *)max_jit_obex_new(class_max_jit_foo,
gensym("jit_foo")))
{
// add a general purpose outlet (rightmost)
max_jit_obex_dumpout_set(x, outlet_new(x,0L));

// get normal args if necessary

attrstart = max_jit_attr_args_offset(argc,argv);

// instantiate Jitter object

if (o = jit_object_new(gensym("jit_foo")))
{
// set internal jitter object instance
max_jit_obex_jitob_set(x,o);

// process attribute arguments

max_jit_attr_args(x,argc,argv);
}
else
{
// couldn’t instantiate, clean up and report an error
freeobject((void *)x);
x = NULL;
error("jit.foo: out of memory");
}
}

return (x);
}

20.2 Object Struct

The first thing you must do is define your Max class object struct. As is typical, for standard Max objects the first
entry of the object struct must be of type t_object; for UI objects, it must be of type t_jbox; for MSP objects, it must
be of type t_pxobject; and for MSP UI objects, it must be of type t_pxjbox. For more information on these different
Max object types, please consult the Max developer documentation. Jitter objects can be wrapped within any of
these object types.
You also need to define a pointer to point to extra information and resources needed to effectively wrap your Jitter
class. This is typically referred to as the "obex" data, and it is where Jitter stores things like attribute information,
the general purpose "dumpout", the internal Jitter object instance, Matrix Operator resources for inlets/outlets, and
other auxiliary object information that is not required in a simple Max object. As of Max 4.5 there is also the facility
for making use of such additional object information for ordinary Max objects. At the time of this writing, such
information is provided in the Pattr developer documentation, as it is relevant to the definition of object attributes,
which may be stored and operated upon by the patcher attribute suite of objects.

20.3 Defining Your Max Class

In your Max class registration, which takes place in your external's ext_main() function, you should begin by calling
your Jitter class's registration function, typically named something like your_object_name_init(). Then you should
proceed to define the Max class's constructor, destructor, object struct size, and typed arguments as is typically
accomplished for Max objects via the setup function. In order for your wrapper class to be able to find the obex data,
you need to specify a byte offset where this pointer is located within each object instance and allocate the resource

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

20.4 Constructor 81

in which this is stored in your Max class. This is accomplished with the max_jit_classex_setup() function. You
should then look up the Jitter class via jit_class_findbyname(), and wrap it via the max_jit_classex_standard_wrap()
function. The max_jit_classex_standard_wrap() function will add all typed methods defined in the Jitter class, as
well getter and setter methods for attributes that are not opaque (i.e. private), and all the methods that are common
to Jitter objects like getattributes, getstate, summary, importattrs, exportattrs, etc.
Now that you have wrapped the Jitter class, you can add any additional methods that you wish, such as your
inlet/outlet assistance method, or something specific to the Max object. Like Jitter objects, you can also add methods
which have defer or usurp wrappers, and these should be added via the max_addmethod_defer_low() or max_←-
addmethod_usurp_low() functions, rather than simply using the traditional addmess() function. C

20.4 Constructor

Inside the Max object constructor, there are a few things which are different than building an ordinary Max external.
If your object is to respond to attribute arguments, the constructor must be defined to take variable number of typed
atom arguments, accomplished with the A_GIMME signature. You allocate your Max object with the max_jit_←-
obex_new() function, instead of the traditional newobject function. You need to pass your Jitter class name to the
max_jit_obex_new() function, which also allocates and initializes your obex data. If successful, you should proceed
to add your general purpose "dumpout" outlet, used for returning attribute queries and other methods that provide
information like ∗jit.movie∗'s framedump method's frame number or read method success code, with the max_←-
jit_object_dumpout_set() function. If your object is a Matrix Operator that calls max_jit_mop_setup_simple() you
will not need to explicitly call max_jit_object_dumpout_set(), as max_jit_mop_setup_simple() calls max_jit_object←-
_dumpout_set() internally.
You then allocate your Jitter object with jit_object_new(), and store it in your obex data via max_jit_obex_jitob_set().
Note that this Jitter object instance can always be found with the function max_jit_obex_jitob_get(). If you wish,
prior to allocating your Jitter object, you can look at your non-attribute arguments first — those arguments up to
the location returned by max_jit_attr_args_offset() — and make use of them in your Jitter object constructor. It is
typical to process attribute arguments after you've allocated both the Max and Jitter object instances, with max←-
_jit_attr_args(), which is passed the Max object instance. If you wanted to use the attribute arguments somehow
in your Jitter object constructor, you would need to parse the attribute arguments yourself. If you are not able to
allocate your Jitter object (as is the case if you have run out of memory or if Jitter is present but not authorized), it is
important that you clean up your Max wrapper object, and return NULL.

20.5 Destructor

In your Max object destructor, you additionally need to free your internal Jitter object with jit_object_free(), and free
any additional obex data with max_jit_obex_free(). Matrix operators will typically require that max_jit_mop_free() is
called, to free the resources allocated for matrix inputs and outputs. If your object has attached to a registered object
for notification via jit_object_attach(), you should detach from that object in your destructor using jit_object_detach()
to prevent invalid memory accesses as the registered object might attempt to notify the memory of a now freed
object. Object registration and notification is discussed in further detail in following chapters.

20.6 Dumpout

The general purpose outlet, also known as "dumpout", is automatically used by the Max wrapper object when calling
attribute getters and several of the standard methods like summary, or getattributes. It is also available for use in
any other Max method you want, most easily accessed with the max_jit_obex_dumpout() function that operates
similar to outlet_anything(), but uses the max object pointer rather than the outlet pointer as the first argument.
The outlet pointer which has been set in your constructor can be queried with the max_jit_obex_dumpout_get()
function, and used in the standard outlet calls. However, it is recommended for routing purposes that any output
through the dumpout outlet is a message beginning with a symbol, rather than simply a bang, int, or float. Therefore,
outlet_anything() makes the most sense to use.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

82 Jitter Max Wrappers

20.7 Additional inlets/outlets

To add additional inlets and outlets to your Max external, a few things should be noted. First, if your object is a Matrix
Operator, matrix inlets and outlets will be added either through either the high level max_jit_mop_setup_simple(), or
lower level max_jit_mop_inputs() or max_jit_mop_outputs() calls. These Matrix Operator functions will be covered
in the chapter on Matrix Operators. Secondly, if your object is an MSP object, all signal inlets and outlets must be
leftmost, and all non-signal inlets and outlets must be to the right of any single inlets or outlets—i.e. they cannot be
intermixed. Lastly, additional inlets should use proxies (covered in detail in the Max developer documentation) so
that your object knows which inlet a message has been received. This is accomplished with the max_jit_obex_←-
proxy_new() function. The inlet number is zero based, and you do not need to create a proxy for the leftmost inlet.
Inside any methods which need to know which inlet the triggering message has been received, you can use the
max_jit_obex_inletnumber_get() function.

20.8 Max Wrapper Attributes

Sometimes you will need additional attributes which are specific to the Max wrapper class, but are not part of the
internal Jitter class. Attributes objects for the Max wrapper class are defined in the same way as those for the
Jitter class, documented in the previous chapter. However, these attributes are not added to the Max class with the
jit_class_addattr() function, but instead with the max_jit_classex_addattr() function, which takes the classex pointer
returned from max_jit_classex_setup(). Attribute flags, and custom getter and setter methods should be defined
exactly as they would for the Jitter class.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 21

Matrix Operator QuickStart

The purpose of this chapter is to give a quick and high level overview of how to develop a simple Matrix Operator
(MOP), which can process the matrix type most commonly used for video streams—i.e.
4 plane char data. For this task, we will use the jit.scalebias SDK example. More details such as how to make a
Matrix Operator which deals with multiple types, plane count, dimensionality, inputs, outputs, etc. will appear in the
following chapter. This chapter assumes familiarity with Jitter's multi-dimensional matrix representation and Matrix
Operators used from the Max patcher, as discussed in the Jitter Tutorial, and as well as the preceding chapters on
the Jitter object model and Max wrapper classes.

21.1 Defining the MOP Jitter Class

In the Jitter class definition, we introduce a few new concepts for Matrix Operators. In addition to the standard
method and attribute definitions discussed in the Jitter object model chapter, you will want to define things like how
many inputs and outputs the operator has, and what type, plane count, and dimension restrictions the operator has.
These are accomplished by creating an instance of the jit_mop class, setting some state for the jit_mop object and
adding this object as an adornment to your Jitter class. The following code segment references the jit.scalebias
SDK example.

// create a new instance of jit_mop with 1 input, and 1 output

mop = jit_object_new(_jit_sym_jit_mop,1,1);

// enforce a single type for all inputs and outputs

jit_mop_single_type(mop,_jit_sym_char);

// enforce a single plane count for all inputs and outputs

jit_mop_single_planecount(mop,4);

// add the jit_mop object as an adornment to the class

jit_class_addadornment(_jit_scalebias_class,mop);

You create your jit_mop instance in a similar fashion to creating your attribute instances, using jit_object_new(). The
jit_mop constructor has two integer arguments for inputs and outputs, respectively. By default, each MOP input
and output is unrestricted in plane count, type, and dimension, and also are linked to the plane count, type, and
dimensions of the first (i.e. leftmost) input. This default behavior can be overridden, and this simple 4 plane, char
type, jit.scalebias example enforces the corresponding type and plane count restrictions via the jit_mop_single_←-
type() and jit_mop_single_planecount() utility functions. For more information on the jit_mop class, please see the
following chapter on MOP details and the Jitter API reference.
Once you have created your jit_mop instance, and configured it according to the needs of your object, you add it as
an adornment to your Jitter class with the jit_class_add_adornment() function. Adornments are one way for Jitter
objects to have additional information, and in some instances behavior, tacked onto an existing class. Adornments
will be discussed in detail in a later chapter.
You also want to define your matrix calculation method, where most of the work of a Matrix Operator occurs, with
the jit_class_addmethod() function as a private, untyped method bound to the symbol matrix_calc.
84 Matrix Operator QuickStart

jit_class_addmethod(_jit_scalebias_class,
(method)jit_scalebias_matrix_calc,
"matrix_calc", A_CANT, 0L);

21.2 The Jitter Class Constructor/Destructor

You don't need to add anything special to your Matrix Operator's constructor or destructor, aside from the stan-
dard initialization and cleanup any Jitter object would need to do. Any internal matrices for input and outputs are
maintained, and only required, by the Max wrapper's asynchronous interface. The Jitter MOP contains no matrices
for inputs and outputs, but rather expects that the matrix calculation method is called with all inputs and outputs
synchronously. When used from languages like C, Java, and JavaScript, it is up to the programmer to maintain and
provide any matrices which are being passed into the matrix calculation method.

21.3 The Matrix Calculation Method

The most important method for Matrix Operators, and the one in which the most work typically occurs is in the
matrix calculation, or "matrix_calc" method, which should be defined as a private, untyped method with the A_←-
CANT type signature, and bound to the symbol "matrix_calc". In this method your object receives a list of input
matrices and output matrices to use in its calculation. You need to lock access to these matrices, inquire about
important attributes, and ensure that any requirements with respect to type, plane count, or dimensionality for the
inputs are met before actually processing the data, unlocking access to the matrices and returning. It should be
defined as in the following example.

t_jit_err jit_scalebias_matrix_calc(t_jit_scalebias *x,

void *inputs, void *outputs)
{
t_jit_err err=JIT_ERR_NONE;
long in_savelock,out_savelock;
t_jit_matrix_info in_minfo,out_minfo;
char *in_bp,*out_bp;
long i,dimcount,planecount,dim[JIT_MATRIX_MAX_DIMCOUNT];
void *in_matrix,*out_matrix;

// get the zeroth index input and output from

// the corresponding input and output lists
in_matrix = jit_object_method(inputs,_jit_sym_getindex,0);
out_matrix = jit_object_method(outputs,_jit_sym_getindex,0);

// if the object and both input and output matrices

// are valid, then process, else return an error
if (x&&in_matrix&&out_matrix)
{
// lock input and output matrices
in_savelock =
(long) jit_object_method(in_matrix,_jit_sym_lock,1);
out_savelock =
(long) jit_object_method(out_matrix,_jit_sym_lock,1);

// fill out matrix info structs for input and output

jit_object_method(in_matrix,_jit_sym_getinfo,&in_minfo);
jit_object_method(out_matrix,_jit_sym_getinfo,&out_minfo);

// get matrix data pointers

jit_object_method(in_matrix,_jit_sym_getdata,&in_bp);
jit_object_method(out_matrix,_jit_sym_getdata,&out_bp);

// if data pointers are invalid, set error, and cleanup

if (!in_bp) { err=JIT_ERR_INVALID_INPUT; goto out;}
if (!out_bp) { err=JIT_ERR_INVALID_OUTPUT; goto out;}

// enforce compatible types

if ((in_minfo.type!=_jit_sym_char) ||
(in_minfo.type!=out_minfo.type))
{
err=JIT_ERR_MISMATCH_TYPE;
goto out;
}

// enforce compatible planecount

if ((in_minfo.planecount!=4) ||
(out_minfo.planecount!=4))
{

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

21.4 Processing N-Dimensional Matrices 85

err=JIT_ERR_MISMATCH_PLANE;
goto out;
}

// get dimensions/planecount
dimcount = out_minfo.dimcount;
planecount = out_minfo.planecount;
for (i=0;i<dimcount;i++)
{
// if input and output are not matched in
// size, use the intersection of the two
dim[i] = MIN(in_minfo.dim[i],out_minfo.dim[i]);
}

// calculate, using the parallel utility function to

// call the calculate_ndim function in multiple
// threads if there are multiple processors available
jit_parallel_ndim_simplecalc2(
(method)jit_scalebias_calculate_ndim,
x, dimcount, dim, planecount,
&in_minfo, in_bp, &out_minfo, out_bp,
0, 0);
} else {
return JIT_ERR_INVALID_PTR;
}

out:
// restore matrix lock state to previous value
jit_object_method(out_matrix,_jit_sym_lock,out_savelock);
jit_object_method(in_matrix,_jit_sym_lock,in_savelock);
return err;
}

21.4 Processing N-Dimensional Matrices

Since Jitter supports the processing of N-dimensional matrices where N can be any number from 1 to 32, most
Matrix Operators are designed with a recursive function that will process the data in some lower dimensional slice,
most often 2 dimensional. The recursive function that does this is typically named myobject_calculate_ndim(), and
is called by your matrix_calc method either directly or via one of the parallel processing utility functions, which are
discussed in a future chapter.
It is out of the scope of this documentation to provide a detailed tutorial on fixed point or pointer arithmetic, both
of which are used in this example. The code increments a pointer through the matrix data, scaling each planar
element of each matrix cell by some factor and adding some bias amount. This is done with fixed point arithmetic
(assuming an 8bit fractional component), since a conversion from integer to floating point data and back is an
expensive operation. The jit.scalebias object also has two modes, one which sums the planes together, and one
which processes each plane independently. You can improve performance by case handling on a per row, rather
than per cell basis, and reduce your code somewhat by case handling on a per row, rather than per matrix basis.
While a slight performance increase could be made by handling on a per matrix basis, per row is usually a decent
point at which to make such an optimization trade off.

// recursive function to handle higher dimension matrices,

// by processing 2D sections at a time
void jit_scalebias_calculate_ndim(t_jit_scalebias *x,
long dimcount, long *dim, long planecount,
t_jit_matrix_info *in_minfo, char *bip,
t_jit_matrix_info *out_minfo, char *bop)
{
long i,j,width,height;
uchar *ip,*op;
long ascale,rscale,gscale,bscale;
long abias,rbias,gbias,bbias,sumbias;
long tmp;

if (dimcount<1) return; //safety

switch(dimcount)
{
case 1:
// if only 1D, interpret as 2D, falling through to 2D case
dim[1]=1;
case 2:
// convert floating point scale factors to a fixed point int
ascale = x->ascale*256.;
rscale = x->rscale*256.;
gscale = x->gscale*256.;

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

86 Matrix Operator QuickStart

bscale = x->bscale*256.;

// convert floating point bias values to a fixed point int

abias = x->abias*256.;
rbias = x->rbias*256.;
gbias = x->gbias*256.;
bbias = x->bbias*256.;

// for efficiency in sum mode (1), make a single bias value

sumbias = (x->abias+x->rbias+x->gbias+x->bbias)*256.;

width = dim[0];
height = dim[1];

// for each row

for (i=0;i<height;i++)
{
// increment data pointers according to byte stride
ip = bip + i*in_minfo->dimstride[1];
op = bop + i*out_minfo->dimstride[1];

switch (x->mode) {
case 1:
// sum together, clamping to the range 0-255
// and set all output planes
for (j=0;j<width;j++) {
tmp = (long)(*ip++)*ascale;
tmp += (long)(*ip++)*rscale;
tmp += (long)(*ip++)*gscale;
tmp += (long)(*ip++)*bscale;
tmp = (tmp>>8L) + sumbias;
tmp = (tmp>255)?255:((tmp<0)?0:tmp);
*op++ = tmp;
*op++ = tmp;
*op++ = tmp;
*op++ = tmp;
}
break;
default:
// apply to each plane individually
// clamping to the range 0-255
for (j=0;j<width;j++) {
tmp = (((long)(*ip++)*ascale)>>8L)+abias;
*op++ = (tmp>255)?255:((tmp<0)?0:tmp);
tmp = (((long)(*ip++)*rscale)>>8L)+rbias;
*op++ = (tmp>255)?255:((tmp<0)?0:tmp);
tmp = (((long)(*ip++)*gscale)>>8L)+gbias;
*op++ = (tmp>255)?255:((tmp<0)?0:tmp);
tmp = (((long)(*ip++)*bscale)>>8L)+bbias;
*op++ = (tmp>255)?255:((tmp<0)?0:tmp);
}
break;
}
}
break;
default:
// if processing higher dimension than 2D,
// for each lower dimensioned slice, set
// base pointer and recursively call this function
// with decremented dimcount and new base pointers
for (i=0;i<dim[dimcount-1];i++)
{
ip = bip + i*in_minfo->dimstride[dimcount-1];
op = bop + i*out_minfo->dimstride[dimcount-1];
jit_scalebias_calculate_ndim(x,dimcount1,
dim,planecount,in_minfo,ip,out_minfo,op);
}
}
}

Rather than using multidimensional arrays, Jitter matrix data is packed in a single dimensional array, with defined
byte strides for each dimension for greatest flexibility. This permits matrices to reference subregions of larger
matrices, as well as support data that is not tightly packed. Therefore, rather than using multidimensional array
syntax, this code uses pointer arithmetic to access each plane of each cell of the matrix, adding the corresponding
byte strides to the base pointer for each dimension across which it is iterating. These byte strides are stored in the
dimstride entry of the t_jit_matrix_info struct. Note that Jitter requires that planes within a cell, and cells across the
first dimension (dim[0]) are tightly packed. The above code assumes that this is the case, using a simple pointer
increment for each plane and cell, rather than looking up byte strides for dim[0].

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

21.5 Defining the MOP Max Wrapper Class 87

21.5 Defining the MOP Max Wrapper Class

In order to use the MOP class in a Max patcher you need to make a Max wrapper class. In addition to the standard
methods used to wrap any Jitter class, MOPs need to add special methods and information to the Max class. One of
the things that needs to happen is that the Max wrapper class needs to allocate and maintain instances of jit.matrix
for each matrix input and output other than the leftmost input, to accommodate Max's asynchronous event model. In
order to perform this maintenance, the Max wrapper class must have special methods and attributes for setting the
type, plane count, dimensions, adaptability, and named references for the internal matrices. All of these messages
are exclusive to the Max wrapper implementation, and are not used by the C, Java, or JavaScript usage of Matrix
Operators. There are also common methods and attributes for the matrix output mode, and the jit_matrix and bang
messages, all of which are specific to the MOP's Max wrapper. These special attributes and methods are added by
the max_jit_classex_mop_wrap() function, which should be called inside your Max external's ext_main() function,
after calling max_jit_classex_setup() and jit_class_findbyname(), and before calling max_jit_classex_standard_←-
wrap(). Several default methods and attributes can be overridden using the various flags that can be combined for
the flags argument to max_jit_classex_mop_wrap(). These flags, which for most simple MOPs won't be necessary,
are listed below.

#define MAX_JIT_MOP_FLAGS_OWN_ALL 0xFFFFFFFF

#define MAX_JIT_MOP_FLAGS_OWN_JIT_MATRIX 0x00000001
#define MAX_JIT_MOP_FLAGS_OWN_BANG 0x00000002
#define MAX_JIT_MOP_FLAGS_OWN_OUTPUTMATRIX 0x00000004
#define MAX_JIT_MOP_FLAGS_OWN_NAME 0x00000008
#define MAX_JIT_MOP_FLAGS_OWN_TYPE 0x00000010
#define MAX_JIT_MOP_FLAGS_OWN_DIM 0x00000020
#define MAX_JIT_MOP_FLAGS_OWN_PLANECOUNT 0x00000040
#define MAX_JIT_MOP_FLAGS_OWN_CLEAR 0x00000080
#define MAX_JIT_MOP_FLAGS_OWN_NOTIFY 0x00000100
#define MAX_JIT_MOP_FLAGS_OWN_ADAPT 0x00000200
#define MAX_JIT_MOP_FLAGS_OWN_OUTPUTMODE 0x00000400

21.6 The Max Class Constructor/Destructor

Inside your Max class' constructor you need to allocate the matrices necessary for the MOP inputs and outputs,
the corresponding matrix inlets and outlets, process matrix arguments and other MOP setup. The max_jit_mop_←-
setup_simple() function takes care of these functions and some of the other necessary tasks of wrapping your Jitter
instance. As such, the use of this function simplifies your Jitter class wrapping even further for the simple case
where no special behavior, incompatible with max_jit_mop_setup_simple() is required. Here is the constructor for
the Max class of the jit.scalebias object.

void *max_jit_scalebias_new(t_symbol *s, long argc, t_atom *argv)

{
t_max_jit_scalebias *x;
void *o;

if (x = (t_max_jit_scalebias *)
max_jit_obex_new(
max_jit_scalebias_class,
gensym("jit_scalebias")))
{
// instantiate Jitter object
if (o=jit_object_new(gensym("jit_scalebias")))
{
// handle standard MOP max wrapper setup tasks
max_jit_mop_setup_simple(x,o,argc,argv);

// process attribute arguments

max_jit_attr_args(x,argc,argv);
}
else
{
error("jit.scalebias: could not allocate object");
freeobject(x);
}
}
return (x);
}

Below is the listing of the max_jit_mop_setup_simple() function, demonstrating the smaller pieces, it manages for
you. If your object has special requirements, you can use whatever subset of the following function as necessary.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

88 Matrix Operator QuickStart

t_jit_err max_jit_mop_setup_simple(void *x, void *o, long argc,

t_atom *argv)
{
max_jit_obex_jitob_set(x,o);
max_jit_obex_dumpout_set(x,outlet_new(x,NULL));
max_jit_mop_setup(x);
max_jit_mop_inputs(x);
max_jit_mop_outputs(x);
max_jit_mop_matrix_args(x,argc,argv);

return JIT_ERR_NONE;
}

In your Max class' destructor, you need to free the resources allocated for your MOP. This is accomplished with
the max_jit_mop_free() function, which should be called before you free your internal Jitter instance, and your Max
class' obex data. As an example, the jit.scalebias destructor is listed below.

void max_jit_scalebias_free(t_max_jit_scalebias *x)

{
// free MOP max wrapper resources
max_jit_mop_free(x);

// lookup internal Jitter object instance and free

jit_object_free(max_jit_obex_jitob_get(x));

// free resources associated with obex entry

max_jit_obex_free(x);
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 22

Matrix Operator Details

The purpose of this chapter is to fill in the details of what a Matrix Operator is and how it works.
Matrix data in Jitter is typically considered raw data without respect to what the data represents. This permits simple
fundamental operations to be applied to different sorts of data without needing to know any special information.
For this reason most MOPs are general purpose. The jit.scalebias example from the preceding chapter could
be considered video specific in its terminology, and type and plane count restrictions, but fundamentally it is just
calculating a product and sum on each plane of an incoming matrix. In this chapter, we'll cover the details of how to
configure MOP inputs and outputs, any attribute restrictions or linking for those inputs and outputs, what you must
do in your matrix_calc method and how you expose your MOP to the Max environment, overriding default behavior
if necessary.

22.1 Defining the MOP Jitter Class

As discussed in the Matrix Operator Quick Start, for MOPs you must create an instance of jit_mop with the jit_←-
object_new() function and add it to your Jitter class as an adornment with the jit_class_addadornment() function.
The jit_mop object holds information such as how many inputs and outputs the object has, what types, plane count,
and dimension counts are supported, and how inputs should respond to incoming matrices. This information is
only relevant to wrappers of the Jitter object which actually maintain additional matrices for inputs and outputs, as
is the case with the MOP Max wrapper class. When used from C, Java, or JavaScript, it is the the programmer's
responsibility to pass in matrices that conform to any restrictions imposed by the MOP. An example of instantiating
and adding the jit_mop object is below.

// create a new instance of jit_mop with 1 input, and 1 output

mop = jit_object_new(_jit_sym_jit_mop,1,1);

// add jit_mop object as an adornment to the class

jit_class_addadornment(_jit_your_class,mop);

22.2 The jit_mop_io Object

Each instance of jit_mop contains some number of inputs and outputs, specified by the input and output arguments
to the constructor. For each of these inputs and outputs there is an instance of jit_mop_io which records information
specific to that input or output, such as type, plane count, and dimension restrictions. You can access the input or
output objects by calling the getinput or getoutput methods with an integer index argument as below:

input = jit_object_method(mop,_jit_sym_getinput,1);
output = jit_object_method(mop,_jit_sym_getoutput,1);

Once you have obtained references to these inputs or outputs, you may query or set the jit_mop_io attributes.
The attributes typically configured are: types, which is a list of symbols of permitted types, the first of which be-
ing the default; mindim and maxdim, which are the minimum and maximum permitted sizes for each dimension;
90 Matrix Operator Details

mindimcount and maxdimcount, which are the minimum and maximum permitted number of dimensions permitted;
minplanecount and maxplanecount, which are the minimum and maximum number of planes permitted; typelink,
which is the flag that determines if the I/O should change its type to whatever the leftmost incoming matrix is; dim-
link, which is the flag that determines if the I/O should change its dimensions to whatever the leftmost incoming
matrix is; and planelink, which is the flag that determines if the I/O should change its plane count to whatever the
leftmost incoming matrix is.

22.3 Restricting Input/Output Attributes

By default, all types, dimensions and plane count are permitted, and all linking is enabled. If you wish your MOP
to have some specific restrictions, or difference in linking behaviors for any input or output in particular, you can set
the corresponding attributes. For example, to set the plane count to always be four planes, you would set both the
minplanecount and maxplanecount attributes to 4, as below:

output = jit_object_method(mop,_jit_sym_getoutput,1);
jit_attr_setlong(output,_jit_sym_minplanecount,4);
jit_attr_setlong(output,_jit_sym_maxplanecount,4);

The jit.scalebias example could have set the planecount using the minplanecount and maxplanecount attributes
rather than calling the utility function jit_mop_single_planecount(), which internally sets these attributes. A similar
thing could be done to restrict type and dimensions. As for linking, if you wish to develop an object where the right
hand input does not adapt to the size of the leftmost input, as is the case with jit.convolve, you would turn off the
dimlink attribute, as below:

input2 = jit_object_method(mop,_jit_sym_getinput,2);
jit_attr_setlong(input2,_jit_sym_dimlink,0);

Similar could be done to remove type and planecount linking, and the utility functions jit_mop_input_nolink() and
jit_mop_output_nolink() set all of these link attributes to false (zero).

22.4 The ioproc Function

For right hand matrix inputs, incoming data is typically copied by the MOP Max wrapper class. When an incoming
matrix is received by the MOP Max wrapper class, a function called the ioproc is called, and the default ioproc copies
the data, using the current input attributes (which might be linked to the lefthand input). The default ioproc can be
overridden by calling the ioproc method followed by a function with the signature as listed below in the jit_mop_←-
ioproc_copy_adapt() function. The jit_mop_ioproc_copy_adapt() function will always adapt to that inlet's incoming
matrix attributes, as long as they don't conflict with any restrictions. The SDK project for jit.concat demonstrates the
use of the jit_mop_ioproc_copy_adapt() function.

t_jit_err jit_mop_ioproc_copy_adapt(void *mop, void *mop_io, void *matrix)

{
void *m; // destination matrix
t_jit_matrix_info info;

// look up destination matrix from mop_io

if (matrix&&(m=jit_object_method(mop_io,_jit_sym_getmatrix)))
{
// retrieve incoming matrix info
jit_object_method(matrix,_jit_sym_getinfo,&info);

//restrict matrix info based on mop_io attribtues

jit_object_method(mop_io,_jit_sym_restrict_type,&info);
jit_object_method(mop_io,_jit_sym_restrict_dim,&info);
jit_object_method(mop_io,_jit_sym_restrict_planecount,&info);

// set destination matrix info

jit_object_method(m,_jit_sym_setinfo,&info);

// copy the data with the frommatrix method

jit_object_method(m,_jit_sym_frommatrix,matrix,NULL);
}

return JIT_ERR_NONE;
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

22.5 Variable Inputs/Outputs 91

22.5 Variable Inputs/Outputs

You can specify variable input/output MOPs with a negative argument for input and/or outputs when constructing
your jit_mop object. When the using variable inputs and/or outputs, there is not a jit_mop_io for each input and/or
output within your class definition, and therefore the template type, dim, planecount, and linking attributes are not
settable. If anything but the default behavior is required, you must accomplished it in another way — for example,
either by overriding the jit_matrix method of the MOP Max wrapper class, or defining an mproc method to be called
from within the standard jit_matrix method of the MOP Max wrapper class. The jit.pack, jit.unpack, jit.scissors, and
jit.glue objects are a few SDK examples of MOPs with variable inputs and outputs. More information on overriding
the jit_matrix, mproc, and other default methods of the MOP Max wrapper class is covered later in this chapter.

22.6 Adding jit_mop as a Class Adornment

Once you have configured all of the inputs and outputs of your jit_mop object, you must add your jit_mop object to
your Jitter class with the jit_class_addadornment() function. Adorments can be queried from the Jitter class at any
time by calling jit_class_adornment_get() with the Jitter class pointer and the class name of the adornment object,
as demonstrated below.

// add jit_mop object as an adornment to the class

jit_class_addadornment(_jit_your_class,mop);

// look up jit_mop adornment

mop = jit_class_adornment_get(_jit_your_class,
_jit_sym_jit_mop);

22.7 The Matrix Calculation Method

The entry point of the MOP Jitter class is the matrix_calc method, which is passed a list of matrices for the input,
and a list of matrices for the output. It is not the responsibility of the matrix_calc method to perform any copying and
adaptation behavior, but rather simply ensure that the matrices are valid, compatible, and if so, process. Certain
objects may modify the dim, type, or planecount of the output matrices — e.g. the SDK project, jit.thin. However, it is
the calling party's responsibility to perform any copying and conformance to MOP I/O restrictions as defined by the
jit_mop_io objects—i.e. either the Max wrapper class, or the C, Java, or Javascript code which calls the matrix_calc
method.

22.8 Accessing the Input and Output Lists

The input and output lists passed as arguments to your matrix_calc method are Jitter objects, and pointers to the
individual inputs and outputs are acquired by calling the getindex method with an integer argument specifying the
zero based list index. The return values should be tested to make sure they are not null. For example:

// get the zeroth index input and output from

// the corresponding input and output lists
in_matrix = jit_object_method(inputs,_jit_sym_getindex,0);
out_matrix = jit_object_method(outputs,_jit_sym_getindex,0);

// if the object and both input and output matrices

// are valid, then process, else return an error
if (x&&in_matrix&&out_matrix)
{
// ... process data ...

} else {
return JIT_ERR_INVALID_PTR;
}

Technically, you can also pass in an instance of jit_matrix in place of a list for the input or output arguments, since
jit_matrix has a getindex method which returns the jit_matrix instance. This is an example of dynamic binding at
work. Another example of dynamic binding inside the matrix_calc method is that the list elements might be instances

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

92 Matrix Operator Details

of jit_mop_io, rather than instances of jit_matrix. However, since Jitter uses dynamic binding and the jit_mop_←-
io object is a "decorator" class for jit_matrix, all corresponding methods are passed on to the jit_matrix referenced
by the jit_mop_io. In fact, any Jitter objects which respond to the standard interface for jit_matrix could be passed
as inputs or outputs. If this seems confusing, you need not think about the underlying implementation further, but
instead can assume that what is being passed in is simply an instance of jit_matrix. After all it should behave like
one, even if it is not.

22.9 Locking and Unlocking Matrices

Prior to working with a matrix, it is necessary to "lock" it so that the data and attributes will not be changed across
the duration of the operation. This is accomplished by calling the jit_matrix instance's lock method with an integer
argument of 1 (true) to lock the matrix. You should store the current lock state to restore when you're done pro-
cessing. The lock operation should be the first thing to do after ensuring that the matrix objects are not NULL. For
example

// lock input and output matrices

in_savelock = (long) jit_object_method(in_matrix,_jit_sym_lock,1);
out_savelock = (long) jit_object_method(out_matrix,_jit_sym_lock,1);

// ... process data ...

out:
// restore matrix lock state to previous value
jit_object_method(out_matrix,_jit_sym_lock,out_savelock);
jit_object_method(in_matrix,_jit_sym_lock,in_savelock);

22.10 Retrieving Matrix Information

Once you have locked the matrices, you are ready to find out some information about them. This is accomplished
by calling the getinfo method with a pointer to an instance of the t_jit_matrix_info struct. The t_jit_matrix_info struct
contains several common attributes of the matrix and data organization of the matrix data, and is a useful way
to obtain this information in one call, rather than querying each attribute individually. This information is typically
tested to verify compatibility with any assumptions the matrix_calc method needs to make (since this method might
be called from C, Java, or Javascript, you cannot assume that the MOP Max wrapper will have enforced these
assumptions). It is also used to perform the appropriate pointer arithmetic based on type, plane count, dimensions,
and the byte stride of those dimensions, since higher dimensions may not be tightly packed. The t_jit_matrix_info
struct is listed below:

typedef struct _jit_matrix_info

{
long size; // in bytes (0xFFFFFFFF=UNKNOWN)
t_symbol *type; // primitive type
long flags; // matrix flags: my data?, handle?
long dimcount; // # of dimensions
long dim[JIT_MATRIX_MAX_DIMCOUNT]; // dimension sizes
long dimstride[JIT_MATRIX_MAX_DIMCOUNT]; // in bytes
long planecount; // # of planes
} t_jit_matrix_info;

And here is an example of calling the getinfo method to fill out the t_jit_matrix_info struct:

// fill out matrix info structs for input and output

jit_object_method(in_matrix,_jit_sym_getinfo,&in_minfo);
jit_object_method(out_matrix,_jit_sym_getinfo,&out_minfo);

22.11 Retrieving the Data Pointer

The t_jit_matrix_info struct is the meta data, but the actual matrix data can be accessed by acquiring the data
pointer. You accomplish this by calling the matrix's getdata method, passing in a pointer to a pointer. This pointer
can be any type, but it is typically a char (or byte) pointer since you may need to perform bytewise pointer arithmetic

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

22.12 Processing the Data 93

depending on the type and dimstride of your matrix. It is essential to verify that this pointer is valid before attempting
to operate on the data, as demonstrated below.

// get matrix data pointers

jit_object_method(in_matrix,_jit_sym_getdata,&in_bp);
jit_object_method(out_matrix,_jit_sym_getdata,&out_bp);

// if data pointers are invalid, set error, and cleanup

if (!in_bp) { err=JIT_ERR_INVALID_INPUT; goto out;}
if (!out_bp) { err=JIT_ERR_INVALID_OUTPUT; goto out;}

22.12 Processing the Data

While it is possible to incorporate the data processing code inside the matrix_calc method, it is typical to rely on
other routines to accomplish the N dimensional processing through recursion, potentially dispatching to multiple pro-
cessors. The N-dimensional recursive processing function (typically named myobject_calculate_ndim) is discussed
in the next section. You should pass in to the calculate_ndim function your object pointer, the overall dimension
count, dimension sizes, planecount to consider in your calculation, together with the necessary matrix info structs
and data pointers for each input and output. You can call this method directly as is the case in the following code:

// call calculate_ndim function directly in current thread

jit_scalebias_calculate_ndim(x, dimcount, dim, planecount,
&in_minfo, in_bp, &out_minfo, out_bp);

Or you can call this method with the parallel processing utility functions provided with Jitter 1.5 to automatically
dispatch the processing of large matrices across multiple processors when available. This figure illustrates the
dispatching and calculating of the parallel processing utility:
The parallel processing is accomplished by breaking up the matrix into smaller matrices that each reference sub-
regions of the original inputs and outputs. No new objects are created, but rather just additional t_jit_matrix_info
structs and offset data pointers. Jitter 1.5 maintains a pool of worker threads for this purpose, so there is no thread
creation overhead, but rather only some small thread synchronization overhead. Jitter 1.5 only dispatches across
multiple threads when the data count is large enough to justify this thread synchronization overhead.
An important thing worth noting is that if your object performs some kind of spatial operation (e.g. convolution,
rotation, scaling, etc.), you will either need to account for the matrix segmentation used by the parallel utilities or
avoid using parallel processing and call directly in the current thread. Since the jit.scalebias example only processes
one pixel at a time (i.e. a pointwise operation), it is inherently parallelizable, so it takes advantage of multiple
processors as below:

// calculate, using the parallel utility function to

// call the calculate_ndim function in multiple
// threads if there are multiple processors available
jit_parallel_ndim_simplecalc2(
(method)jit_scalebias_calculate_ndim,
x, dimcount, dim, planecount,
&in_minfo, in_bp, &out_minfo, out_bp,
0, 0 );

Important Note: If you aren't sure if your object is a pointwise operator, or don't fully understand how to make your
algorithm parallelizable, you shouldn't use the parallel utility functions in your object. You should simply call the
function directly.

22.13 Processing N-Dimensional Matrices

In the Matrix Operator Quick Start chapter, we discussed how to define a recursive function to process N-
dimensional data in 2D slices, using the jit.scalebias object as an example. This example was restricted to pro-
cessing four plane char data, but many Jitter objects work with any type of data and any plane count. In order to
support all types and plane counts, there needs to be some case handling to know how to step through the data,
and what type data to interpret as so that you can perform the appropriate operations. There are a number of
ways to approach this logic, and decisions to make with respect to optimization. All this case handling can be a bit

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

94 Matrix Operator Details

cumbersome, so when initially developing objects, it probably makes sense for you to focus on a single type and
plane count, and only after you've adequately defined your operation, attempt to make your code robust to process
any type of data and consider optimization of certain cases. The use of C macros, or C++ templates might be
useful things to explore for better code re-use. As for code optimization, typically a decent atomic element to try and
optimize is the "innermost" loop, avoiding branch conditions where possible.
This function is at the heart of the logic you will add in your own custom object. Since there is no "right way" to pro-
cess this data, we won't cover any more code listings for the recursive N-dimensional processing function. However,
the SDK projects that are good examples include: jit.clip, which performs a planar independent, pointwise operation
(limiting numbers to some specified range); jit.rgb2luma, which performs a planar dependent, pointwise operation
(converting RGB color to luminance); and jit.transpose, which performs a planar independent, spatial operation
(rows become columns). For more ideas about N-dimensional matrix processing, we would recommend reading
one of the several books available on 2D signal processing and/or image processing. Most of these concepts are
easily generalized to higher dimensions.

22.14 Defining the MOP Max Wrapper Class

MOP Max wrapper classes typically have a large amount of default behavior, as setup through the max_jit_classex←-
_mop_wrap function, based on the jit_mop Jitter class adornment, and user specified flags. You can either override
all of the default behavior or just specific features. If you wish to override all of the default behavior, you can use
the flag MAX_JIT_MOP_FLAGS_OWN_ALL, when calling the max_jit_classex_mop_wrap() function. If you need to
make use of the jit_mop adornment(), the jit_mop can be looked up by calling the jit_class_adornment_get() method
on the Jitter class. The jit_mop_io inputs and outputs can be queried and their attributes inspected, similar to how
they were set in the MOP Jitter class definition, described earlier in this chapter. Here is an example of how to look
up the jit_mop adornment of the jit.scalebias object:

// look up jitter class by name

jclass = jit_class_findbyname(gensym("jit_scalebias"));
// look up jit_mop adornment
mop = jit_class_adornment_get(jclass,_jit_sym_jit_mop);

22.15 Overriding the jit_matrix Method

By default, a jit_matrix method is added which automatically manages matrix copying and calculation based on the
incoming data. Most typical MOPs simply use the default jit_matrix method. However there are instances where
it is necessary to override the default MOP method to get special behavior, such as recording which matrix input
data is being input to as is the case for the jit.op SDK example, or to do something other than standard copying
and adaptation as is the case for the jit.pack or jit.str.op SDK examples, or to prevent any jit_matrix method at all,
as is the case for the jit.noise SDK example. To prevent the default jit_matrix method from being defined, you can
use the flag MAX_JIT_MOP_FLAGS_OWN_JIT_MATRIX, when calling the max_jit_classex_mop_wrap() function.
To define your own jit_matrix method, you can add an A_GIMME method bound to the symbol jit_matrix, in your
ext_main() function. Here's an example from jit.op:

// add custom jit_matrix method in ext_main()

addmess((method)max_jit_op_jit_matrix, "jit_matrix", A_GIMME, 0);

void max_jit_op_jit_matrix(t_max_jit_op *x, t_symbol *s, short argc,

t_atom *argv)
{
if (max_jit_obex_inletnumber_get(x))
{
// if matrix is received in right input,
// record to override float or int input
x->last = OP_LAST_MATRIX;
}

// now pass on to the default jit_matrix method

max_jit_mop_jit_matrix(x,s,argc,argv);
}

The jit.pack and jit.str.op examples are a bit more involved and also better illustrate the kinds of tasks the default
jit_matrix method performs.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

22.16 Overriding the bang and outputmatrix Methods 95

22.16 Overriding the bang and outputmatrix Methods

A MOP Max wrapper class typically has a bang and outputmatrix method. These two methods are typically equiv-
alent, and by default, both send out the most recently calcuated matrix output. Certain objects that don't have
a matrix output, like the jit.3m SDK example, typcially override these messages with their own bang and some-
times outputmatrix method. These methods can be overridden by using the MAX_JIT_MOP_FLAGS_OWN_BANG
and MAX_JIT_MOP_FLAGS_OWN_OUTPUTMATRIX flags when calling the max_jit_classex_mop_wrap() func-
tion. These flags are typically both passed in together.

22.17 Overriding the name, type, dim, and planecount Attributes

For each input and output, other than the leftmost input, there is, by default, an attribute added to query and set that
input or output's matrix attributes, including name, type, dim, and planecount. While overriding the default attribute
behavior is conceivably necessary to perform very specialized behavior, it is not used by any of the SDK examples.
To prevent the addition of the default attributes for name, type, dim, and planecount, you can use the MAX_J←-
IT_MOP_FLAGS_OWN_NAME, MAX_JIT_MOP_FLAGS_OWN_TYPE, MAX_JIT_MOP_FLAGS_OWN_DIM, and
MAX_JIT_MOP_FLAGS_OWN_PLANECOUNT flags when calling the max_jit_classex_mop_wrap() function. To
define your own attributes, you would follow the same means of defining any attributes for a Max wrapper class with
the appropriate attribute name you wish to override.

22.18 Overriding the clear and notify Methods

By default, a clear and a notify method are added. The default clear method clears each of the input and output
matrices. The default notify method, max_jit_mop_notify(), is called whenever any of the matrices maintained by
the MOP are changed. If it is necessary to respond to additional notifications, it is important to call the max_jit←-
_mop_notify function so that the MOP can perform any necessary maintenance with respect to input and output
matrices, as demonstrated by the jit.notify SDK example. These methods can be overridden using the MAX_JI←-
T_MOP_FLAGS_OWN_CLEAR and MAX_JIT_MOP_FLAGS_OWN_NOTIFY flags, respectively, when calling the
max_jit_classex_mop_wrap() function. Object registration and notification is covered in detail in a future chapter,
but the jit.notify notify method is provided as an example.

// s is the servername, msg is the message, ob is the server object pointer,

// and data is extra data the server might provide for a given message
void max_jit_notify_notify(
t_max_jit_notify *x, t_symbol *s, t_symbol *msg, void *ob, void *data)
{
if (msg==gensym("splat")) {
post("notify: server=%s message=%s",s->s_name,msg->s_name);
if (!data) {
error("splat message NULL pointer");
return;
}
// here’s where we output using the rightmost outlet
// we just happen to know that "data" points to a t_atom[3]
max_jit_obex_dumpout(x,msg,3,(t_atom *)data);
} else {
// pass on to the default Max MOP notification method
max_jit_mop_notify(x,s,msg);
}
}

22.19 Overriding the adapt and outputmode Attributes

By default, adapt and outputmode attributes are added to the MOP Max Wrapper. These attributes determine
whether or not to adapt to incoming matrix attributes, and whether or not the output should calculate a new output
matrix, output the last calculated matrix (freeze), pass on the input matrix (bypass). To prevent the addition of the
default attributes for adapt and outputmode, you can use the MAX_JIT_MOP_FLAGS_OWN_ADAPT, and MAX_←-
JIT_MOP_FLAGS_OWN_OUTPUTMODE flags when calling the max_jit_classex_mop_wrap() function. To define

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

96 Matrix Operator Details

your own attributes, you would follow the same means of defining any attributes for a Max wrapper class with the
appropriate attribute name you wish to override.

22.20 Defining an mproc Method

For many types of operations, it's not required to fully override the default jit_matrix method and any adaptation.
If your object simply needs to override the way in which the Jitter class' matrix_calc method and outlet functions
are called, you can do so by defining an mproc method, which will be called instead of the default behavior. The
jit.3m SDK project is an example where after it calls the Jitter class' matrix_calc method, it queries the Jitter class'
attributes and outputs max messages rather than the default jit_matrix message output.

void max_jit_3m_mproc(t_max_jit_3m *x, void *mop)

{
t_jit_err err;

// call internal Jitter object’s matrix_calc method

if (err=(t_jit_err) jit_object_method(
max_jit_obex_jitob_get(x),
_jit_sym_matrix_calc,
jit_object_method(mop,_jit_sym_getinputlist),
jit_object_method(mop,_jit_sym_getoutputlist)))
{
// report error if present
jit_error_code(x,err);
} else {
// query Jitter class and makes outlet calls
max_jit_3m_bang(x);
}
}

22.21 The Max Class Constructor/Destructor

As we discussed in the Matrix Operator Quick Start, inside your Max class' constructor you need to allocate the
matrices necessary for the MOP inputs and outputs, the corresponding matrix inlets and outlets, process matrix
arguments and other MOP setup. And in your destructor, you need to free oup MOP resources. Typically you would
accomplish this all with the standard max_jit_mop_setup_simple() and max_jit_mop_free() functions, however there
are some instances where you may need to introduce custom behavior.

22.21.1 Variable Inputs/Outputs

The max_jit_mop_setup_simple() function calls max_jit_mop_inputs() and max_jit_mop_outputs() to define any

necessary proxy inlets, outlets, and internal matrices. The listing for these functions are provided below to illus-
trate the default behavior, and a few SDK projects we recommend investigating further are jit.scissors, jit.glue,
jit.pack, and jit.unpack.

t_jit_err max_jit_mop_inputs(void *x)

{
void *mop,*p,*m;
long i,incount;
t_jit_matrix_info info;
t_symbol *name;

// look up object’s MOP adornment

if (x&&(mop=max_jit_obex_adornment_get(x,
_jit_sym_jit_mop)))
{
incount = jit_attr_getlong(mop,_jit_sym_inputcount);

// add proxy inlet and internal matrix for

// all inputs except leftmost inlet
for (i=2;i<=incount;i++) {
max_jit_obex_proxy_new(x,(incount+1)-i); // right to left
if (p=jit_object_method(mop,_jit_sym_getinput,i)) {
jit_matrix_info_default(&info);
max_jit_mop_restrict_info(x,p,&info);
name = jit_symbol_unique();
m = jit_object_new(_jit_sym_jit_matrix,&info);

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

22.21 The Max Class Constructor/Destructor 97

m = jit_object_register(m,name);
jit_attr_setsym(p,_jit_sym_matrixname,name);
jit_object_method(p,_jit_sym_matrix,m);
jit_object_attach(name, x);
}
}
return JIT_ERR_NONE;
}
return JIT_ERR_INVALID_PTR;
}

t_jit_err max_jit_mop_outputs(void *x)

{
void *mop,*p,*m;
long i,outcount;
t_jit_matrix_info info;
t_symbol *name;

if (x&&(mop=max_jit_obex_adornment_get(x,
_jit_sym_jit_mop)))
{
outcount = jit_attr_getlong(mop,_jit_sym_outputcount);

// add outlet and internal matrix for all outputs

for (i=1;i<=outcount;i++) {
max_jit_mop_matrixout_new(x,(outcount)-i);// right to left
if (p=jit_object_method(mop,_jit_sym_getoutput,i)) {
jit_matrix_info_default(&info);
max_jit_mop_restrict_info(x,p,&info);
name = jit_symbol_unique();
m = jit_object_new(_jit_sym_jit_matrix,&info);
m = jit_object_register(m,name);
jit_attr_setsym(p,_jit_sym_matrixname,name);
jit_object_method(p,_jit_sym_matrix,m);
jit_object_attach(name, x);
}
}

return JIT_ERR_NONE;
}
return JIT_ERR_INVALID_PTR;
}

22.21.2 Matrix Arguments

The max_jit_mop_setup_simple() function calls max_jit_mop_matrix_args() to read any matrix arguments, and if
present send them to any linked inputs/outputs and disable the adapt attribute. The listing is provided below to
illustrate the default behavior.

t_jit_err max_jit_mop_matrix_args(void *x, long argc,

t_atom *argv)
{
void *mop,*p,*m;
long incount,outcount,attrstart,i,j;
t_jit_matrix_info info,info2;

if (!(mop=max_jit_obex_adornment_get(x,
_jit_sym_jit_mop)))
return JIT_ERR_GENERIC;

incount = jit_attr_getlong(mop,_jit_sym_inputcount);
outcount = jit_attr_getlong(mop,_jit_sym_outputcount);

jit_matrix_info_default(&info);

attrstart = max_jit_attr_args_offset(argc,argv);
if (attrstart&&argv) {
jit_atom_arg_getlong(&info.planecount, 0, attrstart, argv);
jit_atom_arg_getsym(&info.type, 1, attrstart, argv);
i=2; j=0;
while (i<attrstart) { //dimensions
jit_atom_arg_getlong(&(info.dim[j]), i, attrstart, argv);
i++; j++;
}
if (j) info.dimcount=j;

jit_attr_setlong(mop,_jit_sym_adapt,0); //adapt off

}

jit_attr_setlong(mop,_jit_sym_outputmode,1);

for (i=2;i<=incount;i++) {

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

98 Matrix Operator Details

if ((p=jit_object_method(mop,_jit_sym_getinput,i)) &&
(m=jit_object_method(p,_jit_sym_getmatrix)))
{
jit_object_method(m,_jit_sym_getinfo,&info2);
if (jit_attr_getlong(p,_jit_sym_typelink)) {
info2.type = info.type;
}
if (jit_attr_getlong(p,_jit_sym_planelink)) {
info2.planecount = info.planecount;
}
if (jit_attr_getlong(p,_jit_sym_dimlink)) {
info2.dimcount = info.dimcount;
for (j=0;j<info2.dimcount;j++) {
info2.dim[j] = info.dim[j];
}
}
max_jit_mop_restrict_info(x,p,&info2);
jit_object_method(m,_jit_sym_setinfo,&info2);
}
}

for (i=1;i<=outcount;i++) {
if ((p=jit_object_method(mop,_jit_sym_getoutput,i)) &&
(m=jit_object_method(p,_jit_sym_getmatrix)))
{
jit_object_method(m,_jit_sym_getinfo,&info2);
if (jit_attr_getlong(p,_jit_sym_typelink)) {
info2.type = info.type;
}
if (jit_attr_getlong(p,_jit_sym_planelink)) {
info2.planecount = info.planecount;
}
if (jit_attr_getlong(p,_jit_sym_dimlink)) {
info2.dimcount = info.dimcount;
for (j=0;j<info2.dimcount;j++) {
info2.dim[j] = info.dim[j];
}
}
max_jit_mop_restrict_info(x,p,&info2);
jit_object_method(m,_jit_sym_setinfo,&info2);
}
}

return JIT_ERR_NONE;
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 23

OB3D QuickStart

The purpose of this chapter is to give a quick and high level overview of how to develop a simple Jitter OpenGL
object which draws geometry within a named rendering context - we refer to such an object as an OB3D.
For this task, we will use the jit.gl.simple SDK example. More details such as how to make an OpenGL object which
deals with resources such as display lists and textures, wishes to support matrix input/output, or needs greater
access to OpenGL state will appear in the following chapter. This chapter assumes familiarity with Jitter's OpenGL
object suite used from the Max patcher, as discussed in the Jitter Tutorial, and the preceding chapters on the Jitter
object model and Max wrapper classes.

23.1 Defining the OB3D Jitter Class

Jitter OB3Ds typically are defined to have all or most of the common OB3D attributes and methods discussed in the
Group-OB3D section of the Jitter HTML object reference. These include attributes and methods to set the rendering
destination name, object name, color, lighting, texturing, modelview transform, depth buffering, polygon mode, and
several other common tasks. These common attributes and methods are added by the call to the jit_ob3d_setup()
function in your Jitter class definition, after calling jit_class_new, but typically prior to defining other methods and
attributes. For an OB3D, Jitter needs to store additional information in your object. This information is stored in an
opaque pointer in your object struct, typically named ob3d. The byte offset to your OB3D data pointer is passed into
jit_ob3d_setup(). You can override any default attributes and methods added by jit_ob3d_setup() with the following
flags:

#define JIT_OB3D_NO_ROTATION_SCALE 1 << 0

#define JIT_OB3D_NO_POLY_VARS 1 << 1
#define JIT_OB3D_NO_BLEND 1 << 2
#define JIT_OB3D_NO_TEXTURE 1 << 3
#define JIT_OB3D_NO_MATRIXOUTPUT 1 << 4
#define JIT_OB3D_AUTO_ONLY 1 << 5
#define JIT_OB3D_DOES_UI 1 << 6
#define JIT_OB3D_NO_DEPTH 1 << 7
#define JIT_OB3D_NO_ANTIALIAS 1 << 8
#define JIT_OB3D_NO_FOG 1 << 9
#define JIT_OB3D_NO_LIGHTING_MATERIAL 1 << 10
#define JIT_OB3D_HAS_LIGHTS 1 << 11
#define JIT_OB3D_HAS_CAMERA 1 << 12
#define JIT_OB3D_IS_RENDERER 1 << 13
#define JIT_OB3D_NO_COLOR 1 << 14

Aside from the attributes and methods added to your class by jit_ob3d_setup(), you need to define a private, untyped
method bound to the symbol ob3d_draw. This method is where your object does all its drawing. It is called by the
standard OB3D draw and drawraw methods. The OB3D draw method sets up all of the OpenGL state associated
with the common OB3D attributes before calling your private ob3d_draw method. The drawraw method simply sets
the context before calling your private ob3d_draw method. Because OB3Ds support being named for use within
jit.gl.sketch∗'s drawobject command, you must also add a private, untyped "register" method associated with the
jit_object_register() function. Let's examine the ∗jit.gl.simple SDK project as an example:

t_jit_err jit_gl_simple_init(void)
100 OB3D QuickStart

{
long ob3d_flags = JIT_OB3D_NO_MATRIXOUTPUT; // no matrix output
void *ob3d;

_jit_gl_simple_class = jit_class_new("jit_gl_simple",
(method)jit_gl_simple_new, (method)jit_gl_simple_free,
sizeof(t_jit_gl_simple),0L);

// set up object extension for 3d object, customized with flags

ob3d = jit_ob3d_setup(_jit_gl_simple_class,
calcoffset(t_jit_gl_simple, ob3d),
ob3d_flags);

// define the OB3D draw method. called in automatic mode by

// jit.gl.render or otherwise through ob3d when banged. this
// method is A_CANT because our draw setup needs to happen
// in the ob3d beforehand to initialize OpenGL state
jit_class_addmethod(_jit_gl_simple_class,
(method)jit_gl_simple_draw, "ob3d_draw", A_CANT, 0L);

// define the dest_closing and dest_changed methods.

// these methods are called by jit.gl.render when the
// destination context closes or changes: for example, when
// the user moves the window from one monitor to another. Any
// resources your object keeps in the OpenGL machine
// (e.g. textures, display lists, vertex shaders, etc.)
// will need to be freed when closing, and rebuilt when it has
// changed. In this object, these functions do nothing, and
// could be omitted.
jit_class_addmethod(_jit_gl_simple_class,
(method)jit_gl_simple_dest_closing, "dest_closing", A_CANT, 0L);
jit_class_addmethod(_jit_gl_simple_class,
(method)jit_gl_simple_dest_changed, "dest_changed", A_CANT, 0L);

// must register for ob3d use

jit_class_addmethod(_jit_gl_simple_class,
(method)jit_object_register, "register", A_CANT, 0L);

jit_class_register(_jit_gl_simple_class);

return JIT_ERR_NONE;
}

23.2 The Jitter Class Constructor/Destructor

In your OB3D Jitter Class constructor, you need to pass in your rendering destination name as the first argument.
You should call the jit_ob3d_new() function with your destination name argument to initialize the OB3D data pointer,
associating it with your rendering destination. In your destructor, you need to free your OB3D data pointer with
jit_ob3d_free(). The jit.gl.simple constructor and destructors are below as an example.

t_jit_gl_simple *jit_gl_simple_new(t_symbol *dest_name)

{
t_jit_gl_simple *x;

// make jit object

if (x = (t_jit_gl_simple *)jit_object_alloc(_jit_gl_simple_class))
{
// create and attach ob3d
jit_ob3d_new(x, dest_name);
}
else
{
x = NULL;
}
return x;
}

void jit_gl_simple_free(t_jit_gl_simple *x)

{
// free ob3d data
jit_ob3d_free(x);
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

23.3 The OB3D draw Method 101

23.3 The OB3D draw Method

Your OB3D draw method, bound to the ob3d_draw symbol, is where all of your drawing code takes place. It is called
automatically when your associated jit.gl.render object receives a bang, if your automatic and enabled attributes
are turned on, as they are by default. It is also called if your Max wrapper object receives a bang, or the draw or
drawraw messages. With the exception of the drawraw message, all of the standard OB3D object state is setup
prior to calling your ob3d_draw method, so you needn't setup things like the modelview transform, color, lighting
properties, texture information, if your object doesn't have special needs. The following example from jit.gl.simple,
just draws a simple quadrilateral.

t_jit_err jit_gl_simple_draw(t_jit_gl_simple *x)

{
t_jit_err result = JIT_ERR_NONE;

// draw our OpenGL geometry.

glBegin(GL_QUADS);
glVertex3f(-1,-1,0);
glVertex3f(-1,1,0);
glVertex3f(1,1,0);
glVertex3f(1,-1,0);
glEnd();

return result;
}

Since this example is meant only to show a minimal object which draws geometry with standard OpenGL calls,
there is no texture information or vertex normals specified. However, all standard OpenGL calls should work within
the ob3d_draw method. This example also doesn't show matrix output, as accomplished by jit_ob3d_draw_chunk(),
which will be discussed in the following chapter on OB3D details.

23.4 Defining the OB3D Max Wrapper Class

For OB3Ds, the Max wrapper class has less extra work than for MOPs. In your Max wrapper class definition, you
need only add a call to the max_ob3d_setup() function to add your standard drawing methods, and the max_jit_←-
ob3d_assist() function as your assist method, unless you wish to define your own custom assist method. Everything
else is similar to the standard technique of wrapping a Jitter Class demonstrated in the Max Wrapper Class chapter.

void ext_main(void *r)

{
void *classex, *jitclass;

// initialize Jitter class

jit_gl_simple_init();

// create Max class

setup((t_messlist **)&max_jit_gl_simple_class,
(method)max_jit_gl_simple_new, (method)max_jit_gl_simple_free,
(short)sizeof(t_max_jit_gl_simple), 0L, A_GIMME, 0);

// specify a byte offset to keep additional information about our object

classex = max_jit_classex_setup(calcoffset(t_max_jit_gl_simple, obex));

// look up Jitter class in the class registry

jitclass = jit_class_findbyname(gensym("jit_gl_simple"));

// wrap Jitter class with the standard methods for Jitter objects
max_jit_classex_standard_wrap(classex, jitclass, 0);

// use standard ob3d assist method

addmess((method)max_jit_ob3d_assist, "assist",
A_CANT,0);

// add methods for 3d drawing

max_ob3d_setup();
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

102 OB3D QuickStart

23.5 The Max Class Constructor/Destructor

Your Max class' constructor should be similar to the standard Max wrapper constructor, but the differences worth
noting are that you should pass your first normal argument, which is the rendering destination, on to your Jitter
OB3D constructor, and create a second outlet for matrix output, attached to your object's OB3D data. For your de-
structor, there is nothing additional you need to do for OB3D. The jit.gl.simple Max class' constructor and destructor
are provided as examples.

void *max_jit_gl_simple_new(t_symbol *s, long argc, t_atom *argv)

{
t_max_jit_gl_simple *x;
void *jit_ob;
long attrstart;
t_symbol *dest_name_sym = _jit_sym_nothing;

if (x = (t_max_jit_gl_simple *) max_jit_obex_new(
max_jit_gl_simple_class, gensym("jit_gl_simple")))
{
// get first normal arg, the destination name
attrstart = max_jit_attr_args_offset(argc,argv);
if (attrstart&&argv)
{
jit_atom_arg_getsym(&dest_name_sym, 0, attrstart, argv);
}

// instantiate Jitter object with dest_name arg

if (jit_ob = jit_object_new(
gensym("jit_gl_simple"), dest_name_sym))
{
// set internal jitter object instance
max_jit_obex_jitob_set(x, jit_ob);

// add a general purpose outlet (rightmost)

max_jit_obex_dumpout_set(x, outlet_new(x,NULL));

// process attribute arguments

max_jit_attr_args(x, argc, argv);

// attach the jit object’s ob3d to a new outlet

// this outlet is used in matrixoutput mode
max_jit_ob3d_attach(x, jit_ob, outlet_new(x, "jit_matrix"));
}
else
{
error("jit.gl.simple: could not allocate object");
freeobject((t_object *)x);
x = NULL;
}
}
return (x);
}

void max_jit_gl_simple_free(t_max_jit_gl_simple *x)

{
// lookup our internal Jitter object instance and free
jit_object_free(max_jit_obex_jitob_get(x));

// free resources associated with our obex entry

max_jit_obex_free(x);
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 24

OB3D Details

The purpose of this chapter is to fill in additional details of Jitter OpenGL, which we refer to as OB3Ds.
We will show how to disable and/or override default OB3D attributes and methods, how to support matrix input
and output, and manage resources such as textures, display lists, and shaders. This chapter assumes familiarity
with the OpenGL API and the OB3D Quick Start chapter. It is out of the scope of our documentation to cover the
OpenGL API, so for information on the OpenGL API we recommend consulting the OpenGL Red Book and the
many online tutorials.

24.1 Defining the OB3D Jitter Class

As covered in the OB3D Quick Start, Jitter OB3Ds have a large number of default attributes and methods, and
require some specific methods to be defined. This section seeks to clarify these common attributes and methods
and how to achieve custom behavior where necessary.

24.2 Declaring a Draw Method

All Jitter OB3Ds must define a method bound to the symbol ob3d_draw. This method takes no arguments in addition
to the object struct, and should be defined with the private A_CANT type signature. The private ob3d_draw method
will be called by the standard draw, and drawraw methods that are added to every OB3D. The draw method will set
up OpenGL state associated with the default OB3D attributes before calling ob3d_draw, while the drawraw method
will not.

24.3 Declaring Destination and Geometry Related Methods

It is possible for attributes of a Jitter OB3D or your render destination to change, requiring resources to be freed or
rebuilt. There are three methods used to communicate to an OB3D which such events happen so that the OB3D
can manage resources accordingly. They are: dest_closing, which informs an OB3D that the destination is being
freed, and any context dependent resources such as textures, display lists, and shaders should be freed; dest_←-
changed, which informs an OB3D that the destination has been rebuilt, and new resources can be allocated; and
rebuild_geometry, which informs an OB3D of a change in texture units or some other attribute which affects jit_gl_←-
drawinfo_setup() and other t_jit_gl_drawinfo related functions, such as jit_gl_texcoord, requiring geometry that uses
such functions to be rebuilt. These methods take no arguments in addition to the object struct. The dest_closing
and dest_changed methods should be defined with the private A_CANT type signature, and the rebuild_geometry
method is typically defined as typed, but without arguments, so that users have the ability to explicitly call, if deemed
necessary. The jit.gl.gridshape SDK project is a good example of these methods as it needs to free and allocate
a display list as the render destination changes, and also makes use of jit_gl_texcoord to support multi-texturing,
requiring geometry to be rebuilt as the number of texture units or other attributes change.
104 OB3D Details

24.4 Declaring a Register Method

Since all Jitter OB3D objects are named to support reference by name in jit.gl.sketch, and other objects, it is neces-
sary to add the default registration method, jit_object_register(). Object registration and notification are covered in
detail in a future chapter.

24.5 Overriding Rotation and Scale Related Attributes

By default, each Jitter OB3D has rotate, rotatexyz, scale, and viewalign attributes added to the class by jit_ob3d_←-
setup(), and these attributes are used in the ob3d_draw_preamble() function to set up OpenGL state prior to calling
your object's draw method. These attributes can be disabled by using the JIT_OB3D_NO_ROTATION_SCALE
flag. You can override these attributes by defining your own attributes of the same name, however, you will need to
manage any necessary OpenGL state inside of your own draw method with the appropriate calls to glMatrixMode,
glTranslate, glRotate, and glScale.

24.6 Overriding Color Related Attributes

By default, each Jitter OB3D has color, aux_color, and smooth_shading attributes added to the class by jit_←-
ob3d_setup(), and these attributes are used in the ob3d_draw_preamble function prior to calling your object's draw
method. These attributes can be disabled by using the JIT_OB3D_NO_COLOR flag. You can override these
attributes by defining your own attributes of the same name, however, you will need to manage any necessary
OpenGL state inside of your own draw method with the appropriate calls to glColor and glShadeModel.

24.7 Overriding Texture Related Attributes

By default, each Jitter OB3D has texture, capture, tex_map, tex_plane_s, and tex_plane_t attributes added to the
class by jit_ob3d_setup(), and these attributes are used in the ob3d_draw_preamble() function prior to calling your
object's draw method. These attributes can be disabled by using the JIT_OB3D_NO_TEXTURE flag. You can
override these attributes by defining your own attributes of the same name, however, you will need to manage
any necessary OpenGL state inside of your own draw method with the appropriate calls to glEnable, glTexGen,
jit_gl_bindtexture, jit_gl_unbindtexture, jit_gl_begincapture, and jit_gl_endcapture.

24.8 Overriding Lighting and Material Related Attributes

By default, each Jitter OB3D has lighting_enable, auto_material, shininess, mat_ambient, mat_diffuse, mat_←-
specular, and mat_emission attributes added to the class by jit_ob3d_setup(), and these attributes are used in the
ob3d_draw_preamble function prior to calling your object's draw method. These attributes can be disabled by using
the JIT_OB3D_NO_LIGHTING_MATERIAL flag. You can override these attributes by defining your own attributes
of the same name, however, you will need to manage any necessary OpenGL state inside of your own draw method
with the appropriate calls to glEnable, glLight, glLightModel, and glMaterial.

24.9 Overriding Fog Related Attributes

By default, each Jitter OB3D has fog and fog_params attributes added to the class by jit_ob3d_setup(), and these
attributes are used in the ob3d_draw_preamble function prior to calling your object's draw method. These attributes
can be disabled by using the JIT_OB3D_NO_FOG flag. You can override these attributes by defining your own
attributes of the same name, however, you will need to manage any necessary OpenGL state inside of your own
draw method with the appropriate calls to glEnable, glHint, and glFog.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

24.10 Overriding Polygon Variable Related Attributes 105

24.10 Overriding Polygon Variable Related Attributes

By default, each Jitter OB3D has poly_mode, cull_face, point_size, and line_width attributes added to the class by
jit_ob3d_setup(), and these attributes are used in the ob3d_draw_preamble function prior to calling your object's
draw method. These attributes can be disabled by using the JIT_OB3D_NO_POLY_VARS flag. You can override
these attributes by defining your own attributes of the same name, however, you will need to manage any necessary
OpenGL state inside of your own draw method with the appropriate calls to glPolygonMode, glEnable, glCullFace,
glPointSize, and glLineWidth.

24.11 Overriding Blending Related Attributes

By default, each Jitter OB3D has blend_mode and blend_enable attributes added to the class by jit_ob3d_setup(),
and these attributes are used in the ob3d_draw_preamble function prior to calling your object's draw method. These
attributes can be disabled by using the JIT_OB3D_NO_BLEND flag. You can override these attributes by defining
your own attributes of the same name, however, you will need to manage any necessary OpenGL state inside of
your own draw method with the appropriate calls to glEnable and glBlendFunc.

24.12 Overriding Depth Buffer and Antialiasing Related Attributes

By default, each Jitter OB3D has depth_enable and antialias attributes added to the class by jit_ob3d_setup(), and
these attributes are used in your ob3d_draw_preamble function prior to calling your object's draw method. These
attributes can be disabled by using the JIT_OB3D_NO_DEPTH and JIT_OB3D_NO_ANTIALIAS flags, respectively.
You can override these attributes by defining your own attributes of the same name, however, you will need to
manage any necessary OpenGL state inside of your own draw method with the appropriate calls to glEnable and
glHint.

24.13 Overriding Matrixoutput and Automatic Attributes

By default, each Jitter OB3D has matrixoutput and automatic attributes added to the class by jit_ob3d_setup(), and
these attributes are used in the ob3d_draw_preamble function prior to calling your object's draw method. These
attributes can be disabled by using the JIT_OB3D_NO_MATRIXOUTPUT and JIT_OB3D_AUTO_ONLY flags, re-
spectively. You can override these attributes by defining your own attributes of the same name.

24.14 Declaring a User Interface Object

It is possible to declare a user interface OB3D, such as jit.gl.handle. To do so, you must use the JIT_OB3D_DO←-
ES_UI flag to jit_ob3d_setup(), and define a method bound to the symbol ob3d_ui, with the private A_CANT type
signature and prototype similar to the following example from jit.gl.handle:

t_jit_err jit_gl_handle_ui(t_jit_gl_handle *x,

t_line_3d *p_line, t_wind_mouse_info *p_mouse);

24.15 The Jitter Class Constructor and Destructor

Inside your Jitter class constructor, you must call jit_ob3d_new() with a pointer to your newly allocated object, and
your render destination name. The jit_ob3d_new() function allocates an opaque structure that stores the standard
OB3D attributes and some additional OB3D state, initializing them to default values, and then setting the pointer at
the byte offset specified when calling the jit_ob3d_setup() function in your class definition. If your object supports
matrix output or simply uses the t_jit_glchunk structure when drawing, you should typically allocate your initial

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

106 OB3D Details

t_jit_glchunk in your constructor using the jit_glchunk_new() or jit_glchunk_grid_new() functions. Use of the t_jit←-
_glchunk structure and matrix output is described later in this chapter. Similarly, your OB3D Jitter class destructor
must call jit_ob3d_free() to free the opaque structure used for common OB3D state, free any allocated instances of
t_jit_glchunk with jit_glchunk_free(), and free any other resources allocated such as display lists or textures.

24.16 The OB3D Draw Method

The ob3d_draw method is where all the drawing in your object should take place. It is also where you should
typically allocate context dependent resources or query the context state, since you know that your context is valid
and has been set. For the most part, the drawing you will perform in your ob3d_draw method will be pure and simple
OpenGL, though there are a few caveats which we will cover.

24.17 The t_jit_glchunk Structure and Matrix Output

Since Jitter is a general purpose matrix processing framework, it makes sense that you would have the ability to pass
geometry information through a Jitter network as matrices if your geometry is well suited to a matrix representation.
The cells of your matrix can hold vertex information such as position, texture coordinates, normal vectors, color,
and edge flags, and are documented in the "Geometry Under The Hood" Jitter Tutorial. You also have the option
of specifying a connections matrix to reference the connectivity of the vertices if it is not implicit in the matrix
representation, and a drawing primitive to use when drawing the vertices.
All this information, and whether or not the geometry matrix should be rendered immediately or sent through the
Jitter network is managed with the t_jit_glchunk. An SDK example which demonstrates the use of t_jit_glchunk
is jit.gl.gridshape. The t_jit_glchunk structure along with the vertex matrix it contains is allocated by the jit_←-
glchunk_new() or jit_glchunk_grid_new() functions, freed with the jit_glchunk_delete() function, and drawn with the
jit_ob3d_draw_chunk() function. For reference, the t_jit_glchunk structure and relevant chunk flags are provided
below:

// jit_glchunk is a public structure to store one

// gl-command’s-worth of data, in a format which
// can be passed easily to glDrawRangeElements.

typedef struct _jit_glchunk

{
t_symbol *prim; // GL_TRI_STRIP, GL_TRIANGLES, etc.
t_jit_object *m_vertex; // jit_matrix of xyzst... data.
t_symbol *m_vertex_name; // vertex matrix name
t_jit_object *m_index; // optional 1d connection matrix
t_symbol *m_index_name; // connection matrix name
unsigned long m_flags; // special flags
void *next_chunk; // singly linked list, typically NULL
} t_jit_glchunk;

// flags for chunk creation

#define JIT_GL_CHUNK_IGNORE_TEXTURES 1 << 0
#define JIT_GL_CHUNK_IGNORE_NORMALS 1 << 1
#define JIT_GL_CHUNK_IGNORE_COLORS 1 << 2
#define JIT_GL_CHUNK_IGNORE_EDGES 1 << 3

24.18 OB3D OpenGL Caveats

While you can use any standard Open GL calls inside of your ob3d_draw method. There are a few things worth
noting to follow Jitter conventions. The first of which is the binding of texture coordinates. Since Jitter OB3Ds
support multi-texturing by default, it is not necessarily satisfactory to submit only one texture coordinate with gl←-
TexCoord. Jitter provides some utility routines to set the texture coordinates for as many texture units which are
bound, jit_gl_texcoord(1/2/3)(f/fv). Determining how many texture units have been bound by the default OB3D
attributes requires some overhead, so rather than perform this overhead with every jit_gl_texcoord call, the jit_gl←-
_texcoord functions take a t_jit_gl_drawinfo struct as an argument. This struct can be setup once before rendering
many vertices with the jit_gl_drawinfo_setup function. Example use of jit_gl_texcoord and jit_gl_drawinfo_setup is
in the jit.gl.videoplane SDK project. Another Jitter specific mechanism is the means to bind textures using named

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

24.19 Getting Information About the OB3D Attributes 107

instances of jit.gl.texture. It is possible to create and bind your own textures in an OB3D, but you must then perform
all maintenance instead of relying on jit.gl.texture to handle this work for you. To bind and unbind an instance of
jit.gl.texture, you should call the jit_gl_bindtexture and jit_gl_unbindtexture functions, which take a t_jit_gl_drawinfo
argument, a symbol with the name of the jit.gl.texture instance, and an integer for which texture unit to bind. Unlike
binding ordinary textures in OpenGL, it is important to unbind instances of jit.gl.texture, or else problems may arise.

24.19 Getting Information About the OB3D Attributes

Though the default OB3D attributes are typically relevant to the code which is automatically handled for your object
prior to calling the ob3d_draw method, it is sometimes necessary to access these values. Since the default OB3D
attributes are stored in an opaque ob3d struct member, they are not accessible by your object with a simple struct
pointer dereference. Instead, you need to use the jit_attr_get∗ functions to access these attributes. You should pass
in your object struct as the first argument to these functions rather than your ob3d struct member. For example:

float pos[3];
jit_attr_getfloat_array(x,gensym("position"),3,pos);

Note that if you are acquiring this value often, it is preferable to generate the symbol in advance rather than generate
the symbol for every call.

24.20 Getting Information About the Context

From within the ob3d_draw, dest_closing, and dest_changed methods, the rendering context has always been
set, and you can get a handle to the native context using either the aglGetCurrentContext or wglGetCurrentContext
functions. One can also in these methods use standard OpenGL glGet∗ functions to determine the context's Open←-
GL state, such as the viewport, transformation matrix. It is not recommended to try and acquire the native context
from other methods, or query the OpenGL state as it may not be valid.

24.21 Playing Well with Others

It is important to recognize that OpenGL state is persistent, and that there may be objects which rely on Open←-
GL state that are drawn after your object draws itself. If your object makes any changes to OpenGL state that
might affect objects that follow, you should restore the OpenGL state to whatever it was before your routine was
called. For example, if your object changes the texture transformation matrix, you should push and pop the texture
transformation matrix with glMatrixMode, glPushMatrix, and glPopMatrix, to prevent any problems with other objects.

24.22 Defining the OB3D Max Wrapper Class

As mentioned in the OB3D Quick Start, in your Max wrapper class definition, you need only add a call to the
max_ob3d_setup() function to add your standard drawing methods, and the max_jit_ob3d_assist() function as your
assist method, unless you wish to define your own custom assist method. Everything else is similar to the standard
technique of wrapping a Jitter Class demonstrated in the Max Wrapper Class chapter. Please consult the OB3D
Quick Start chapter and the jit.gl.simple SDK project for all necessary information related to the OB3D Max wrapper
class.

24.23 Matrix Input

Sometimes it is desirable for an OB3D also support incoming matrices as is the case with jit.gl.videoplane or jit.←-
gl.mesh. It is not recommended to mix and match OB3Ds with MOPs. Conflicts arise with respect to arguments,
standard inlets and outlets. Instead, if you wish to support matrix input in your OB3D, you should simply add to your

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

108 OB3D Details

Jitter class a method bound to the symbol jit_matrix, and handle the incoming matrix data according to your needs
- for example as texture data in the case of jit.gl.videoplane, or geometry data in the case of jit.gl.mesh. The jit.gl.←-
videoplane SDK project provides an example of an OB3D which also supports matrix input. When it is necessary
to have multiple input matrices, this is typically managed by either declaring alternately named methods for each
input, or exposing an attribute that specifies which input the jit_matrix method assumes it is being called with. Note
that this requires additional logic within the Max wrapper class to map to inlets, as it is not handled automatically.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 25

Scheduler and Low Priority Queue Issues

In Max, there are a few threads of execution.

The details of these threads are highlighted in the Max documentation and the article, "Event Priority in Max (←-
Scheduler vs. Queue)". In this chapter, we won't cover all these details and restrict our discussion to the scheduler
(which when overdrive is on runs in a separate and high priority thread) and the low priority queue (which always
runs in the main application thread). As far as Jitter is concerned, we won't consider the real time audio thread or
the case of scheduler in audio interrupt, where the scheduler runs in this real time audio thread.
By default, Jitter performs all drawing and matrix processing in the main application thread, with events serviced
from the low priority queue. The reason for this low priority processing is to prevent high timing events such as note
triggering or audio DSP from suffering timing problems due to visual processing. Jitter also exploits the low priority
queue as a mechanism for graceful temporal downsampling of the visual stream in the instance that the processing
requested is too demanding to be calculated in real-time. This results in dropped frames in the output when the
demands cant be met. With audio, it's not sufficient to just drop frames of samples, since there will be an audible
click, but with images, the last image will persist if a new one isn't generated at some fixed sampling rate.

25.1 Defer and Usurp

The mechanisms which enforce execution of Jitter drawing and matrix processing from within the low priority queue
we will call "defer" and "usurp". The defer mechanism will take any high priority events and create a corresponding
low priority event at the end of the low priority queue. The defer mechanism ensures that the events will not
be executed from the high priority scheduler thread, but does not prevent scheduler backlog with the temporal
downsampling mentioned above. To accomplish this, the usurp mechanism mush be used. The usurp mechanism
will use no more than one low priority queue element for the task requested (either a method call or attribute setter).
The way usurp works is that if there is no pending event for the method or attribute call, a new event is placed at the
end of the low priority queue. If there is already an event pending, the usurp mechanism will not place a new event
on the end of the low priority queue, but rather "usurp" the arguments for the event waiting to being passed to the
method or attribute call. This way, if a high priority metronome is rapidly sending values to set an attribute, while the
initial low priority event is waiting to be processed, the value to be set is constantly being updated ("usurped") and
only the value at the time of servicing the event will be used.
It is important to note that the defer and usurp mechanisms only work as called from within the Max patcher. For
any methods which are called from a text based programming language, such as C, Java, or JavaScript, the defer
and usurp mechanisms are bypassed. This may be something you need to pay attention to and handle yourself if
you are making such calls from a text based programming language and need the defer or usurp behavior.

25.2 Using Defer and Usurp in Jitter Object Methods

When defining a method in Jitter, there is the possibility to define a type signature for the method just as one would
do in Max. Typical type signatures include typical atom elements such as A_LONG, A_FLOAT, and A_SYM; or the
110 Scheduler and Low Priority Queue Issues

corresponding default value versions A_DEFLONG, A_DEFFLOAT, A_DEFSYM; or the variable argument version
A_GIMME which provides a list of atoms and the number of atoms provided; or the private and untyped status
of A_CANT used for methods which are not exposed to the patcher and require additional C function prototype
information in order to call. While these type signatures can be used within Jitter objects, most methods exposed to
the patcher interface make use of either the defer or usurp mechanism as defined by two new type signatures A_←-
DEFER_LOW or A_USURP_LOW. Methods defined with the A_DEFER_LOW, or A_USURP_LOW type signatures
should conform to the same variable argument prototype as A_GIMME methods, but behind the scenes, Jitter will
make use of the defer and usurp mechanism to enforce the appropriate behavior.
An example of two methods from jit.gl.videoplane which use these mechanisms is below:

// add a usurping jit_matrix method

jit_class_addmethod(_jit_gl_videoplane_class, (method)jit_gl_videoplane_jit_matrix
, "jit_matrix", A_USURP_LOW, 0);

// add a deferred sendtexture method

jit_class_addmethod(_jit_gl_videoplane_class, (method)
jit_gl_videoplane_sendtexture, "sendtexture", A_DEFER_LOW, 0);

The implementation of these methods is below:

void jit_gl_videoplane_jit_matrix(t_jit_gl_videoplane *x, t_symbol *s, int argc,

t_atom *argv)
{
t_symbol *name;
void *m;
t_jit_matrix_info info;
long dim[2];

if ((name=jit_atom_getsym(argv)) != _jit_sym_nothing) {
m = jit_object_findregistered(name);
if (!m) {
error("jit.gl.videoplane: couldn’t get matrix object!");
return;
}
}

if (x->texture) {
jit_object_method(m, _jit_sym_getinfo, &info);
jit_attr_getlong_array(x->texture,_jit_sym_dim,2,dim);
jit_object_method(x->texture,s,s,argc,argv);
jit_attr_setsym(x,ps_texture,x->texturename);
}
}

void jit_gl_videoplane_sendtexture(t_jit_gl_videoplane *x, t_symbol *s, int argc,

t_atom *argv)
{
if (x->texture) {
s = jit_atom_getsym(argv);
argc--;
if (argc)
argv++;
else
argv = NULL;
object_method_typed(x->texture,s,argc,argv,NULL);
}
}

From inspecting the header files, you may note that there are also A_DEFER and A_USURP type signatures, but
these should be considered obsolete, as they make use of the problematic deferral strategy of placing the event at
the front of the low priority queue and have the potential of reversing message sequencing.

25.3 Using Defer and Usurp in Jitter Object Attributes

Unlike methods, attributes do not make use of type signatures for their getter and setter accessor methods. Instead
they should always be prototyped similar to A_GIMME, but with an attribute object being passed in place of the
traditional method symbol pointer of the A_GIMME signature. So the way you can specify to use the defer and
usurp mechanisms for attribute accessors are through the attribute flags argument to the attribute constructor. For
the getter accessor method, you can use JIT_ATTR_GET_DEFER_LOW or JIT_ATTR_GET_USURP_LOW flags.
For the setter accessor method, you can use JIT_ATTR_SET_DEFER_LOW or JIT_ATTR_SET_USURP_LOW
flags.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

25.4 Using Defer and Usurp in the Max Wrapper Object 111

An example attribute definition from jit.gl.videoplane is below:

attrflags = JIT_ATTR_GET_DEFER_LOW |
JIT_ATTR_SET_USURP_LOW;
attr = jit_object_new(_jit_sym_jit_attr_offset,"displaylist",
_jit_sym_char,attrflags,
(method)0L,(method)jit_gl_videoplane_displaylist,calcoffset(t_jit_gl_videoplane,
displaylist));
jit_class_addattr(_jit_gl_videoplane_class,attr);

You may have noticed that like previous code example, all Jitter object attributes which are not private have been de-
fined with getter accessors which use the defer mechanism (JIT_ATTR_GET_DEFER_LOW) and setter accessors
which use the usurp mechanism (JIT_ATTR_SET_USURP_LOW). This is the recommended style of exposing Jitter
object attributes to the patcher, since there are many cases where at high priority an attribute is set repeatedly and
we want both the latest high priority value when the next calculation is made at low priority and no low priority queue
backlog from generating more events at high priority than can be processed at low priority. The defer mechanism is
used for getter accessor methods so that every attribute query results in a corresponding output message out the
dump outlet. Otherwise certain patcher logic could easily become confused. If a different behavior is required by
the Max programmer, they can make use of the jit.qball object to force either the defer or usurp mechanisms to be
used for their message stream.

25.4 Using Defer and Usurp in the Max Wrapper Object

Most of the above is also true when declaring methods and attributes in the Max wrapper object, however the func-
tion calls which are used are slightly different. You must use the special max object function calls max_addmethod←-
_defer_low() and max_addmethod_usurp_low() for methods, and max_jit_classex_addattr() for attributes. Below
are examples from jit.matrixset. Note that there is no type signature provided for either max_addmethod_defer_←-
low() or max_addmethod_usurp_low().

// add a deferred "exportmovie" method

max_addmethod_defer_low((method)max_jit_matrixset_export_movie, "exportmovie")
;

// add a usurped outputmatrix method

max_addmethod_usurp_low((method)max_jit_matrixset_outputmatrix, "
outputmatrix");

// add index attribute

attrflags = JIT_ATTR_GET_DEFER_LOW |
JIT_ATTR_SET_USURP_LOW ;
attr = jit_object_new(_jit_sym_jit_attr_offset,"index",
_jit_sym_long,attrflags,
(method)0L,(method)0L,calcoffset(t_max_jit_matrixset,index));
max_jit_classex_addattr(p,attr);

25.5 When Not to Use the Usurp Mechanism

The bang method for Jitter MOP objects uses the usurp mechanism to drop frames when the number of bang
messages cannot be handled in real time. However, jit.gl.render's bang method does not behave this way, and
instead uses the defer mechanism. At first this might seem counterintuitive, however, because rendering in Open←-
GL with jit.gl.render uses a group of messages to perform erasing, any non automatic drawing of objects, and then a
drawing of automatic clients and a swap to the screen with the bang method, it is not an atomic action (i.e. requires a
sequence of different events rather than a single event). Since the usurp mechanism is method or attribute specific
with regard to the events which are being usurped, it only works for atomic actions. For this reason, it is important
for users to perform some drop framing behavior before triggering the message sequence, typically accomplished
with qmetro or jit.qball. If your object has some operation which requires a sequence of events in a similar fashion
as jit.gl.render, then it would be best to use the defer mechanism rather than the usurp mechanism for relevant
methods.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

112 Scheduler and Low Priority Queue Issues

25.6 Overriding Defer and Usurp

There are instances where the user does not wish to be limited to processing Jitter matrices at low priority, such as
when Jitter matrices are used for tasks other than realtime image processing–for example, parameter interpolation
or matrices containing audio data. For these tasks, the jit.qfaker object is provided for advanced users which are
aware of the potential problems involved in bypassing these low priority mechanisms. As mentioned above, when
programming in a text based language, these mechanisms aren't used and all method and attribute accessor calls
are synchronous. Therefore there typically isn't a need to consider overriding this behavior from a text based
language. However, for certain externals which wish to simulate the jit.qfaker behavior, we expose the max_jit←-
_queuestate() function to override Jitter's detection of queue state for the defer and usurp mechanisms. It is also
possible to query what jitter believes the queue state to be with the max_jit_getqueuestate() function. This is the
function employed by the defer and usurp mechanisms. The source code for these functions is below for reference.

long max_jit_queuestate(long state)

{
long rv=_max_jit_queuestate;

_max_jit_queuestate = (state!=0);

return rv;
}

long max_jit_getqueuestate(void)
{
// always return true if faking
if (_max_jit_queuestate) return 1;

return !sched_isinpoll();
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 26

Jitter Object Registration and Notification

In Jitter, matrices are passed around as named references between Max objects.
This named reference is created since Jitter registers these matrices with the corresponding name using the jit_←-
object_register() function. Object registration is useful for a few reasons. First, registered matrices can be resolved
by name using the jit_object_findregistered() function. Secondly, registered objects can sent event notification
to clients who have attached to them using jit_object_attach(). Lastly, under certain circumstances, the object
registration process can be used to have multiple external references to a single instance of an object as is the case
with jit.matrix.

26.1 Registering Named Objects

To register an object, one can use the jit_object_register() function, which is equivalent to the Max object_register()
function in the namespace associated with gensym("jitter"). Traditionally in Jitter, we bind jit_object_register() to the
"register" method for an object and use jit_object_method() to call this method. For example, from the jit.notify SDK
example:

// allocate the Jitter object

if (o=jit_object_new(gensym("jit_notify"))) {
...
// generate a unique name
x->servername = jit_symbol_unique();

// register the object with the given name

jit_object_method(o,_jit_sym_register,x->servername);
...
}

If not using a specific name, it is good to use the jit_symbol_unique() function as above to generate a unique name
which is slated for re-use once a registered object is freed. This prevents excess memory usage by the symbol
table as associated with these unique names.
If you wish the object to have multiple references to a single instance with some name, as is common with the
jit.matrix object, it is essential to use the return value of jit_object_register() in any instance where the object pointer
is saved after registration. This is because if the registered object with the same class already exists, the object
attempting to be registered will be freed, and the already registered object of the same class will be returned, its
reference count having been incremented. This is not typically an issue outside of registering jit.matrix objects,
although you may have a need for this type of implementation in other situations. Most other situations in which
object registration is used within Jitter only expects and/or permits a single instance to be registered. In the above
example, we know that this is safe to do, as we are using jit_symbol_unique() to generate a unique name.
It is also possible to unregister named objects, with the jit_object_unregister() function, but typically this is handled
for you when your object is freed, or if your object is registered again with a different name. This is not often used in
the Jitter code base except within these contexts.
114 Jitter Object Registration and Notification

26.2 Looking Up an Object by Name

Registered objects can be found by name using the jit_object_findregistered() function. For example named ma-
trices are resolved using this function. Most Matrix Operator objects have this done for them by the default MOP
code, but for example any MOP which has its own jit_matrix method, such as the jit.pack SDK example will make
use of jit_object_findregistered() inside its jit_matrix method:

// get our matrix name from the atom arguments provided

matrixname = jit_atom_getsym(argv);

// look up based on name

matrix = jit_object_findregistered(matrixname);

// make sure that it is a valid pointer and has a "class_jit_matrix" method which returns 1
if (matrix&&jit_object_method(matrix, _jit_sym_class_jit_matrix)) {
...
}

26.3 Attaching to Named Objects

Once an object has been registered, it can be considered a server to which clients attach to be notified of various
events. To attach to a named object, use the the jit_object_attach() function. Similarly to detach from a named
object, use the jit_object_detach() function. It is typical to detach from a server in your object's destructor, or any
time your object is switching which server it is attached to. For your client object to receive any notification from the
server object, it is important for your object to have defined a "notify" method which will receive the notification from
all objects it is attached to.
Below is the jit.notify SDK example's max wrapper object's notify method, which receives some atom values from
its internal Jitter object instance. Since this object is a Matrix Operator, it is important in the following example
that jit.notify calls the max_jit_classex_mop_wrap() function with the MAX_JIT_MOP_FLAGS_OWN_NOTIFY flag
to override the default MOP notify method, and that we pass on all other messages to the standard max_jit_mop←-
_notify() method so that the default MOP code is informed of any changes to the input and output matrices.

// s is the servername, msg is the message, ob is the server object pointer,

// and data is extra data the server might provide for a given message
void max_jit_notify_notify(t_max_jit_notify *x, t_symbol *s, t_symbol *msg, void *ob, void
*data)
{
if (msg==gensym("splat")) {
post("notify: server=%s message=%s",s->s_name,msg->s_name);
if (!data) {
error("splat message NULL pointer");
return;
}
// here’s where we output using the rightmost outlet
// we just happen to know that "data" points to a t_atom[3]
// alternately you could use max_jit_obex_dumpout_get just to get
// the outlet pointer
max_jit_obex_dumpout(x,msg,3,(t_atom *)data);
} else {
// since we are a MOP, we are also attached to all the matrices for each input/output
// so we need to deal with this by calling the default mop notify method
// (this is how mops handle their matrices getting new names/freed/modified)
max_jit_mop_notify(x,s,msg);
}
}

26.4 Notifying Clients

If you are making an object which is to be registered, and wish to send custom notification to clients in addition to
the default notification that attributes send to all clients when the attribute is modified, and the default object free
notification, then you will want to use the jit_object_notify() function. This function lets you determine a message
name to use for notification and optionally specify additional, but untyped data to all clients. If you choose to send
additional data to clients, it is necessary for all client code to know how to unpack this information. Below is the
example from the jit.notify SDK example which uses the notification mechanism to send some data to its max
wrapper object:

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

26.4 Notifying Clients 115

t_atom foo[3];

jit_atom_setlong(&foo[0],1);
jit_atom_setlong(&foo[1],2);
jit_atom_setlong(&foo[2],3);
jit_object_notify(x,gensym("splat"), foo);

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

116 Jitter Object Registration and Notification

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 27

Using Jitter Objects in C

When developing for Jitter in C, the functionality of pre-existing Jitter objects can be used.
In this chapter, we'll briefly examine instantation and incorporation of the features of the jit.movie and jit.qt.record
objects from your C code.

27.1 Example 1: the t_jit_qt_movie object

Using an object like t_jit_qt_movie from your own code is fairly straightforward. Since it's a standard Jitter ob-
ject, we can use jit_object_new() and jit_object_free() for instantiation and freeing, jit_object_method() for sending
messages, and jit_attr_get... and jit_attr_set... for getting and setting attributes.
For instance, in the following code snippet, we'll create a t_jit_qt_movie object, read a pre-specified movie from disk,
and decompress its first frame into a matrix, set to the native size of the movie.

void jit_foo_read_first_movie_frame(
t_jit_foo *x, t_symbol *s, long ac, t_atom *av)
{
void *qtmovie;

// create the t_jit_qt_movie object, sized to 1x1

qtmovie = jit_object_new(gensym("jit_qt_movie"), 1, 1);
if (qtmovie) {
t_atom rv; // will contain rvarr, with any return values
// from our "read" call
t_object *rvarr; // the t_atomarray with the actual
// return values

// turn off autostart

jit_attr_setlong(qtmovie, gensym("autostart"), 0);
// read the movie, just pass in the args to our function
object_method_typed(qtmovie, gensym("read"), ac, av, &rv);

// check the return value & verify that the movie loaded
if (rvarr = jit_atom_getobj(&rv)) {
long rvac = 0;
t_atom *rvav = NULL;

object_getvalueof(rvarr, &rvac, &rvav);

if (rvac && rvav) {
// just as in Max, we get a list: "filename success";
// success of 1 means the read was successful
if (rvac > 1 && jit_atom_getlong(rvav + 1)) {
long dim[2];
void *matrix;
t_jit_matrix_info info;

// get our movie’s native dims

jit_attr_getlong_array(qtmovie, gensym("movie_dim"),
2, dim);
// set the t_jit_qt_movie’s dim to match
jit_object_method(qtmovie,_jit_sym_dim,dim[0],dim[1]);
// set our matrix up to match
jit_matrix_info_default(&info);
info.type = _jit_sym_char;
info.planecount = 4;
118 Using Jitter Objects in C

info.dimcount = 2;
info.dim[0] = dim[0];
info.dim[1] = dim[1];
matrix = jit_object_new(_jit_sym_jit_matrix, &info);
if (matrix) {
// call the t_jit_qt_movie’s matrix_calc method
// with our matrix as an argument
err = (t_jit_err)jit_object_method(qtmovie,
_jit_sym_matrix_calc, NULL, matrix);
if (err != JIT_ERR_NONE) {
error("something went wrong");
}
// do something with the matrix

// free the matrix

jit_object_free(matrix);
}
}
freebytes(rvav, sizeof(t_atom) * rvac);
}
freeobject(rvarr);
}
jit_object_free(qtmovie);
}
}

Naturally, we could also set the t_jit_qt_movie object's time attribute, or call its or frame method, to recall an arbitrary
point in time. In fact, nearly every documented method and attribute of the jit.movie object, as it functions in the Max
interface, is available from C. The exceptions are those functions implemented in the Max wrapper object, such as
framedump.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 28

JXF File Specification

The Jitter File Format (JXF) stores matrix data in a binary (not human-readable) form.
When using Jitter you can create JXF files by sending the write message to a jit.matrix object. Conversely you can
read JXF files from disk using the read message. This section will cover first the API functions that one can use
from C to read and write JXF files. Then it will break down the file format at the bit level.

28.1 The Binary JXF API

Most Jitter users do not need or want to know about the internal binary format of a JXF-file. Even users who want
to read and write JXF-files from C do not need to know the internal details if they use the functions of the Jitter API
for the binary interface. Not only is the API more convenient, but using the functions provided by Cycling '74 may
protect your code from having to be altered in the future in the event of a specification change.
There are two primary functions one should use to read data from a JXF file. jit_bin_read_header() reads the
version number and the size of the file from the header, and has the following signature:

t_jit_err jit_bin_read_header(t_filehandle fh, ulong *version, long *

filesize)

jit_bin_read_matrix() imports matrix data from a file to a matrix, resizing the matrix if necessary, and has the following
signature:

t_jit_err jit_bin_read_matrix(t_filehandle fh, void *matrix)

Here’s a chunk of code that shows how to read a matrix from disk:

if (!(err=path_opensysfile(filename, path, &fh, READ_PERM))) {

//all is well
} else {
error("jit.matrix: can’t open file %s",name->s_name);
goto out;
}
if (jit_bin_read_header(fh,&version,&filesize)) {
error("jit.matrix: improper file format %s",name->s_name);
sysfile_close(fh);
goto out;
}
if (jit_bin_read_matrix(fh,matrix)) {
error("jit.matrix: improper file format %s",name->s_name);
sysfile_close(fh);
goto out;
}
sysfile_close(fh);

Similarly there are two functions one should use when writing data to a JXF file. jit_bin_write_header() writes a
header to a file, and has the following signature:
120 JXF File Specification

t_jit_err jit_bin_write_header(t_filehandle fh, long filesize)

jit_bin_write_matrix() writes a matrix to a file, and has the following signature:

t_jit_err jit_bin_write_matrix(t_filehandle fh, void *matrix)

Here’s a section of code that shows how you might write a file with one matrix. Note that the initial filesize argument
to jit_bin_write_header() is bogus, but that the header is written again at the end of the operation when the filesize
can be determined from the file position after writing the matrix.

if (err=path_createsysfile(filename, path, type, &fh)) {

error("jit.matrix: could not create file %s",name->s_name);
goto out;
}
if (jit_bin_write_header(fh,0)) {
error("jit.matrix: could not write header %s", matrixName->s_name);
sysfile_close(fh);
goto out;
}
if (jit_bin_write_matrix(fh,pointerToMatrix)) {
error("jit.matrix: could not write matrix %s", matrixName->s_name);
sysfile_close(fh);
goto out;
}
sysfile_getpos(fh, &position);
sysfile_seteof(fh, position);
if (jit_bin_write_header(fh,position)) {
error("jit.matrix: could not write header %s",
matrixName->s_name);
sysfile_close(fh);
goto out;
}
sysfile_close(fh);

28.2 Specification of the JXF Format

The internal format of JXF-files is based on the Interchange File Format (IFF) (http://en.wikipedia.←-
org/wiki/Interchange_File_Format). An IFF file is built up from chunks. All data in IFF files is big-
endian. Several convenience macros defined in jit.byteorder.h are available to help convert numbers to the proper
format before and after they're written to and read from a JXF file: BE_I32() can be called on 32-bit integers,
BE_F32() on 32-bit floats, and BE_F64() on 64-bit doubles.
Each chunk in an IFF file begins with a four character Type ID. This is followed by a 32-bit unsigned integer specifying
the size of the chunk content in bytes. In a JXF file, the 32-bit integer part of the first chunk tells us the size of the
file, and all the subsequent chunks, which begin immediately after the first chunk, contain matrices. In the future
chunks may also be used to store other kinds of data.
Here is a tabular overview of an example minimal JXF file.
Container Chunk
groupID JIT_BIN_CHUNK_CONTAINER ('FORM')
File size 32-bit int
IFF Type JIT_BIN_FORMAT ('JIT!')
Format Chunk

chunkID JIT_BIN_CHUNK_FORMAT_VERSION ('FVER')

Chunk size 12 bytes
Version JIT_BIN_VERSION_1 (0x3C93DC80)
Matrix Chunk
chunk ID JIT_BIN_CHUNK_MATRIX ('MTRX')

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

28.2 Specification of the JXF Format 121

chunk size 32-bit int

offset 32-bit int
type 4-char
planecount 32-bit int
dimcount 32-bit int
dim Array of 32-bit ints that contain the dimensions
data
The data offset of the matrix chunk represents the offset, in bytes, from the beginning of the chunk to the beginning
of the data portion of the chunk. The type is one of CHAR, LONG, FL32 and FL64. The dim array contains dimcount
elements, each of which is a 32-bit int. The data portion consists of the cells of the matrix written out one at a time
in row-major order. Planar data is multiplexed in each cell. For example, a 3-plane 2 by 2 matrix would be written
out in the following order:
Plane Dim 0 Dim 1
0 0 0
1 0 0
2 0 0
0 1 0
1 1 0
2 1 0
0 0 1
1 0 1
2 0 1
0 1 1
1 1 1
2 1 1
The various chunks discussed above can be represented by the C structs listed below:

typedef struct _jit_bin_chunk_container

{
ulong ckid; //’FORM’
long cksize; //filesize
ulong formtype; //’JIT!’
} t_jit_bin_chunk_container;

typedef struct _jit_bin_chunk_format_version

{
ulong ckid; //’FVER’
long cksize; //12
ulong vers; //timestamp
} t_jit_bin_chunk_format_version;

typedef struct _jit_bin_chunk_matrix

{
ulong ckid; //’MTRX’
long cksize; //varies(should be equal to
//24+(4*dimcount)+(typesize*planecount*totalpoints))
long offset; //data offset(should be equal to 24+(4*dimcount))
ulong type; //’CHAR’,’LONG’,’FL32’,’FL64’
long planecount;
long dimcount;
long dim[1];
} t_jit_bin_chunk_matrix;

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

122 JXF File Specification

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 29

Jitter Networking Specification

This appendix describes the format of the data sent by a jit.net.send object.
The object attempts to form a TCP connection with a host at the IP and port specified by the object's attributes. Any
program wishing to receive data will therefore have to set itself up as a host and listen for incoming TCP connections.
Once a connection is formed, data can be sent. Data is sent as a stream of chunks. The first thing received will be
a chunk header. It consists of a 32-bit chunk ID and a 32-bit int representing the size of the next chunk to come.
The chunk ID can be one of the following 4-char symbols, depending on what kind of packet it is:

#define JIT_MATRIX_PACKET_ID ’JMTX’

#define JIT_MATRIX_LATENCY_PACKET_ID ’JMLP’
#define JIT_MESSAGE_PACKET_ID ’JMMP’

This chunk header could be represented in C by the following struct:

typedef struct _jit_net_packet_header

{
t_int32 id;
t_int32 size; //size of packet to come
} t_jit_net_packet_header;

If the chunk is a matrix packet, the next data received will be a header of 288 bytes with the following contents:
id 'JMTX'
Size 288 (32-bit int, size of this header)
Planecount 32-bit int
Type 32-bit int, 0 for char, 1 for long, 2 for float32, 3 for
float64
Dimcount 32-bit int
Dim Array of 32 32-bit ints
Dimstride Array of 32 32-bit ints
Datasize 32-bit int, size of the data buffer to come
Time 64-bit double precision float
This chunk could be represented with the following C struct:

typedef struct _jit_net_packet_matrix

{
t_int32 id;
t_int32 size;
t_int32 planecount;
t_int32 type; //0=char,1=long,2=float32,3=float64
t_int32 dimcount;
t_int32 dim[JIT_MATRIX_MAX_DIMCOUNT];
t_int32 dimstride[JIT_MATRIX_MAX_DIMCOUNT];
t_int32 datasize;
double time;
} t_jit_net_packet_matrix;

Following this header the next data received will be the matrix data, the size of which was passed in the above
header. When using the data, please note the dimstrides transmitted in the header.
124 Jitter Networking Specification

The time field in the above header will be set to the time of transmission from the sending computer. jit.net.send
expects the server to respond by sending back timing data of its own – it uses this data to estimate the transmission
latency. The exact data in the latency chunk that jit.net.send expects to receive is the following:
id 'JMLP'
client_time_original 64-bit double, the time value received in the matrix
header packet
server_time_before_data 64-bit double, the time on the server when the packet
header is received
server_time_after_data 64-bit double, the time on the server after the packet
has been processed and is in use

This chunk can be represnted by the following C struct:

typedef struct _jit_net_packet_latency

{
t_int32 id;
double client_time_original;
double server_time_before_data;
double server_time_after_data;
} t_jit_net_packet_latency;

The difference between the server time before and server time after processing the data represents the time it
takes the server to mobilize the data after it has been received. jit.net.send will send and expects to receive time
in milliseconds. When this timing information is received by the transmitting computer, it notes its current time,
calculates the round trip time and then estimates the latency as half the round trip time plus half of the server
processing time. This estimate is accurate if the time of flight from A to B is the same as the time of flight from B
to A, but network topology can be very complicated, and often the route from A to B is not the reverse of the route
from B to A. In simple situations, such as a direct connection between two computers or a small LAN, the estimate
should be reasonably accurate.
Finally, the last type of packet that can be sent is the message packet. The size of the message packet is sent in the
initial header packet. Standard A_GIMME messages (t_symbol ∗s, long ac, t_atom ∗av) are serialized starting with
a 32-bit integer that contains the size of the serialized message in bytes. Following that another 32-bit integer gives
the argument count for the atoms. Following that comes the message atoms themselves, starting with the leading
symbol if it exists. Each atom is represented in memory first with a char that indicates what type of atom it is: 's'
for symbol, 'l' for long, and 'f' for float. For long and float atoms, the next 4 bytes contain the value of the atom; for
symbol atoms a null terminated character string follows.
All data is represented with little endian byte ordering.
Below is a C function that will deserialize a message passed in as a data pointer.

void gimme_deserialize(char *data, t_symbol **s, long *ac, t_atom **av)

{
char *curr = data;
float *currf;
long *currl,i;
long datasize = BE_I32(*((long *)curr));
curr += sizeof(long);
*ac = BE_I32(*(long *)(curr));
curr += sizeof(long);
*av = (t_atom *)sysmem_newptr(sizeof(t_atom)*(*ac));

if (*curr == ATOM_SERIALIZATION_SYMBOL_CODE)
{
curr++;
*s = gensym(curr);
while (*(++curr) != ’\0’) ;
curr++;
}
else
*s = 0L;
for (i=0;i<*ac;i++)
switch (*curr++)
{
case ATOM_SERIALIZATION_SYMBOL_CODE:
(*av)[i].a_type = A_SYM;
(*av)[i].a_w.w_sym = gensym(curr);
while (*(++curr) != ’\0’) ;
curr++;

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

 125

break;
case ATOM_SERIALIZATION_FLOAT_CODE:
(*av)[i].a_type = A_FLOAT;
(*av)[i].a_w.w_float = BE_F32(*((float *)curr));
curr += sizeof(float);
break;
case ATOM_SERIALIZATION_LONG_CODE:
(*av)[i].a_type = A_LONG;
(*av)[i].a_w.w_long = BE_I32(*((long *)curr));
curr += sizeof(long);
break;
}
}

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

126 Jitter Networking Specification

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 30

Appendix: Messages sent to Objects

When writing objects for Max, you typically think of creating methods which are called when a message is sent to
your object through the object's inlet.
However, your object may receive messages directly from Max rather than using the inlet.
One common example is the "assist" message, which is sent to your object when a user's mouse cursor hovers
over one of your object's inlets or outlets. If your object binds a method to the "assist" message then you will be
able to customize the message that is shown.
This appendix serves as a quick reference for messages that are commonly sent to objects by Max, should they be
implemented by the given object. Where possible, the prototypes given are actual prototypes from example objects
in the SDK rather than abstractions to assist in finding the context for these calls.

30.1 Messages for All Objects

acceptsdrag_locked long pictmeter_acceptsdrag_←-

unlocked(t_pictmeter ∗x, t_object
∗drag, t_object ∗view);
acceptsdrag_unlocked long pictmeter_acceptsdrag_←-
unlocked(t_pictmeter ∗x, t_object
∗drag, t_object ∗view);
assist void pictmeter_assist(t_pictmeter
∗x, void ∗b, long m, long a, char
∗s);
dumpout bind this message to
object_obex_dumpout() rather
than defining your own method.
inletinfo void my_obj(t_object ∗x, void ∗b, you may bind to stdinletinfo() or
long a, char ∗t) define your own inletinfo method.

The 'b' parameter can be ignored,

the 'a' parameter is the inlet
number, and 1 or 0 should set the
value of '∗t' upon return.
128 Appendix: Messages sent to Objects

notify t_max_err
dbviewer_notify(t_dbviewer ∗x,
t_symbol ∗s, t_symbol ∗msg, void
∗sender, void ∗data);
stdargs t_max_err my_obj(t_dictionary ∗d, when loading an old (Max 3 or 4)
t_symbol ∗s, long argc, t_atom patcher, this will be called prior to
∗argv) your new method. You can then fill
in the dictionary with key/value
pairs from your previous args.
quickref obsolete, this is provided
automatically now

30.2 Messages for Non-UI Objects

dblclick void scripto_dblclick(t_scripto ∗x);

30.3 Messages for User Interface Objects

getdrawparams void
uisimp_getdrawparams(t_uisimp
∗x, t_object ∗patcherview,
t_jboxdrawparams ∗params);
mousedown void scripto_ui_mousedown(t_←-
scripto_ui ∗x, t_object
∗patcherview, t_pt pt, long
modifiers);
mouseup void uisimp_mouseup(t_uisimp ∗x,
t_object ∗patcherview, t_pt pt, long
modifiers);
mousedrag void scripto_ui_mousedrag(t_←-
scripto_ui ∗x, t_object
∗patcherview, t_pt pt, long
modifiers);
mouseenter void uisimp_mouseenter(t_uisimp
∗x, t_object ∗patcherview, t_pt pt,
long modifiers);
mouseleave void uisimp_mouseleave(t_uisimp
∗x, t_object ∗patcherview, t_pt pt,
long modifiers);
mousemove void uisimp_mousemove(t_uisimp
∗x, t_object ∗patcherview, t_pt pt,
long modifiers);
paint void pictmeter_paint(t_pictmeter
∗x, t_object ∗patcherview);

30.4 Message for Audio Objects

dsp void plus_dsp(t_plus ∗x, t_signal

∗∗sp, short ∗count);
dspstate plus_dspstate(t_plus ∗x, long n);

30.5 Messages for Objects Containing Text Fields

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

30.6 Messages for Objects with Text Editor Windows 129

key long uitextfield_key(t_uitextfield ∗x,

t_object ∗patcherview, long
keycode, long modifiers, long
textcharacter);
keyfilter long
uitextfield_keyfilter(t_uitextfield ∗x,
t_object ∗patcherview, long
∗keycode, long ∗modifiers, long
∗textcharacter);
enter void uitextfield_enter(t_uitextfield
∗x);
select void uitextfield_select(t_uitextfield
∗x);

30.6 Messages for Objects with Text Editor Windows

edclose void
simpletext_edclose(t_simpletext
∗x, char ∗∗text, long size);

30.7 Messages for Dataview Client Objects

getcelltext void
dbviewer_getcelltext(t_dbviewer
∗x, t_symbol ∗colname, long
index, char ∗text, long maxlen);
newpatcherview void dbviewer_newpatcherview(t←-
_dbviewer ∗x, t_object
∗patcherview);
freepatcherview void dbviewer_freepatcherview(t←-
_dbviewer ∗x, t_object
∗patcherview);

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

130 Appendix: Messages sent to Objects

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 31

Appendix: Providing Icons for UI Objects

If you are writing user interface objects for Max, it is recommended that you provide an icon for your object.
Providing an icon will allow users to create an instance of your class from the object palette, and improve the user's
experience in other interactions with Max including the Object Defaults inspector.

31.1 Object SVG Icon

To see the icons provided by Cycling '74 for objects included in Max, look in the Cycling '74/object-icons folder
installed by Max. You will find a variety of SVG (scalable vector graphics) files for the objects. The files are named
with the same name of the class (as it is defined in your ext_main() function) with which they are associated.
SVG files can be edited in a variety of software applications such as InkScape or Adobe Illustrator. You can also
export SVG files from OmniGraffle on the Mac, which is how the Max's object icons were created.
It is recommended that you distribute your object as a Max Package (see Appendix: SDK changes for Max 7).
Within this package you shoulo place your svg in the 'interfaces' folder.

31.2 Quick Lookup Definition

Adding the svg file will make the icon available to Max for use in some ways. To make your icon appear in Max's
Object Explorer, however, you must create a quick-lookup (or qlookup) entry for your object. If you look in the
Cycling '74/interfaces folder, you should notice some files with names like "obj-qlookup.json" and "doc-qlookup.←-
json". For your object, you should create a similar qlookup file.
For the following example we will assume you have created an object called 'littleuifoo'. For this object we will create
a qlookup called 'littleuifoo-obj-qlookup.json'. The contents of this file will look like this:

{
"littleuifoo": {
"digest": "Little UI Object that does Foo",
"module": "max",
"category": [
"U/I"
],
"palette": {
"category": [
"Interface"
],
"action": "littleuifoo",
"pic": "littleuifoo.svg"
}
}
132 Appendix: Providing Icons for UI Objects

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 32

Appendix: Additional Resources

While it is out of the scope of this document to cover many topics related to Jitter development, we suggest the
following resources to better inform your development.
The C Programming Language:

• "The C Programming Language", Kernighan and Ritchie (Prentice Hall, 1988). ISBN: 0131103709

• "A Book on C", Kelly and Pohl (Addison Wesley, 1997). ISBN: 0201183994

• Wikipedia's C programming language resources

Object Oriented Programming:

• Wikipedia's Object Oriented Programming resources

• Sun's Object Oriented Programming Concepts Tutorial

• Object Oriented Programming in C

Digital Image Processing:

• "Handbook of Image and Video Processing", A. Bovik et al. (Academic Press, 2000). ISBN: 0121197921

• "Digital Image Processing", W. K. Pratt (John Wiley and Sons, 2001). ISBN: 0471857661

• "Principles of Digital Image Synthesis", A. S. Glassner (Morgan Kaufmann, 1995). ISBN: 1558602763

• Wikipedia's digital image processing resources

Open GL:

• The official OpenGL web portal

Apple and QuickTime:

• Apple's developer resources

Microsoft:

• Micrcosoft's developer resources

134 Appendix: Additional Resources

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 33

Appendix: Updating Externals for Max 6

33.1 Updating MSP Externals for 64-bit Audio Processing

33.1.1 Background

In Max 5 and prior versions, the signal chain for processing audio was compiled by sending all objects in the patcher
a "dsp" message. Objects responding to this message then executed their dsp method, typically adding one of the
object's perform methods to the signal chain.
In Max 6, the signal chain is compiled by first sending objects a "dsp64" message. When your object responds to
this message, you can add your 64-bit audio perform methods. If an object supports the old "dsp" message but not
the "dsp64" message, it then wraps the older 32-bit perform routine with conversion on the inputs and outputs.
This means that the 64-bit engine will work just fine with the older 32-bit objects. However, the conversion comes
with some computational expense. For the best performance your objects should support the 64-bit dsp chain
natively by implementing the "dsp64" message as explained below.

33.1.2 API

As noted, instead of the "dsp" method used by objects for Max 5 and earlier, Max 6 objects implement a "dsp64"
method. This has the same purpose as the original dsp method. One notable difference is that the signals are not
passed to the dsp64 method. This is to allow for the signal that is used to change dynamically at runtime. However,
the relevant info (samplerate, number of signals connected, etc) is passed in.
The main purpose of the dsp64 method is to call back into the audio lib to put perform methods on the dsp chain.
This is done by sending the 'dsp_add64' message to the dspchain object using object_method().
The perform routine is now of type t_perfroutine64, defined in z_dsp.h, and now has a fixed function signature. It
does take a user-defined parameter that is passed back from the call to 'dsp_add64'.

33.1.3 Example Code

The simplemsp∼ examples in the 'audio' folder of the SDK have been updated for 64-bit audio processing in Max
6. Several projects, including the simplemsp∼ example, demonstrate how to support both 64-bit audio processing
in Max 6 and 32-bit audio processing for compatibility with Max 5.

33.2 Updating Max Externals for Cocoa

On the Macintosh platform, Max 6 made the transition from using the Carbon API to using the Cocoa API for
interacting with the Mac OS. In most cases the transition for third-party developers should be seemless. If you are
operating directly using native Carbon calls then your code will need to be updated to Cocoa using Objective-C.
136 Appendix: Updating Externals for Max 6

The most common scenario is where you ask a patcherview for the native window handle with a call such as:

WindowRef viewWindow;
object_method(patcherview, gensym("nativewindow"), (void**)&viewWindow);

In Max 6 this will not work because the returned 'viewWindow' is not the Carbon WindowRef but is instead a Cocoa
NSWindow∗. You may update your code to use Cocoa instead of Carbon, or you may wish to transition more slowly
by continuing to use a WindowRef. Here is an example to assist in obtaining a WindowRef:

NSView *cocoa_view = NULL;

NSWindow *cocoa_window = NULL;
WindowRef carbon_window;

object_method(patcherview, gensym("nativewindow"), (void**)&cocoa_view);

if (cocoa_view) {
cocoa_window = [cocoa_view window];
if (cocoa_window) {
carbon_window = [cocoa_window windowRef];
}
}

// now you can use your carbon_window as before

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 34

Appendix: Updating Externals for Max 6.1 (x64

architecture)

34.1 Background

The Max 6.0.x application binary, and the external objects and libraries it uses, are compiled for the i386 processor
architecture. This architecture uses 32-bit memory addressing, meaning that the size of a pointer is 32 bits (or 4
bytes).
Max 6.1 introduces support for the x86_64 (or x64) architecture which uses 64-bit (8 bytes) memory addressing.
Among the benefits are the ability to use more than 2 GB of memory in Max. Additionally, the size of the t_atom is
8-bytes on x64, meaning that double-precision floating pointer numbers can be represented.
For backwards compatibility, Max 6.1 also continues to be distributed as a 32-bit application binary. On the Windows
platform the 32-bit and 64-bit applications are distributed separately, as are the external objects you create for them.
On the Mac platform a Universal Binary (or "FAT" binary) is distributed containing both the 32-bit and 64-bit versions
in the same dynamically-loaded library.
All externals on the Mac remain bundles using the ".mxo" filename extension.
32-bit externals on Windows remain DLLs using the ".mxe" filename extension.
64-bit externals on Windows are still DLLs but use a new ".mxe64" filename extension.

34.1.1 New Types

In addition to the change of size in a pointer, there are some additional changes for 64-bit. For example, a "long"
integer for 32-bit targets is 4 bytes on both the Mac and Windows. However, a "long" integer for 64-bit targets is 4
bytes on Windows but 8 bytes (the size of a pointer) on the Mac!
To facilitate cross platform code that is independent of these platform differences, the Max 6.1 API defines some
new types used throughout the SDK.
Types of fixed size:

t_int8
t_uint8
t_int16
t_uint16
t_int32
t_uint32
t_int64
t_uint64

Types of architecture-dependent size:

t_ptr_int : an int that is the same size as a pointer

138 Appendix: Updating Externals for Max 6.1 (x64 architecture)

t_ptr_uint : an unsigned int that is the same size as a pointer

t_atom_long : the type that is an A_LONG in an atom (32-bits on i386; 64-bits on x64)
t_atom_float : the type that is an A_FLOAT in an atom (float on i386; double on x64)

Types for specific contexts:

t_filepath : i.e. path/vol in file APIs identifying a folder

t_fourcc : use for type codes in locatefile_extended(), file dialogs, etc. to
represent a four char code
t_getbytes_size : if you are using getbytes() and freebytes(), use this type to
represent the size of the memory

34.2 Xcode and Visual Studio Projects

For new objects, you can base projects on those in the new SDK. To update existing projects you will need to make
a few changes to your project settings.

34.2.1 Mac / Xcode

Max 6.1 on the Mac no longer uses the intermediary MaxAPI.framework for linking. Instead, the linking is handled
at runtime and the symbols are checked using special flags to the linker. To update an existing project:

1. remove references to the MaxAPI.framework

2. update the .xcconfig file on which the project is based with the .xcconfig file in the new Max SDK

3. in your target's build settings find the "Other Linker Flags" and set it to "$(C74_SYM_LINKER_FLAGS)"

4. in your target's build settings find the "Architectures" and set it to "i386 x86_64"

34.2.2 Windows / Visual Studio

In order to build for x64 with Visual Studio 2008, you must have the "Pro" version. The free "Express" version will
not work. The "Express" versions of Visual Studio 2010 and 2012 do work (2012 is recommended).
Due to bugs in Visual Studio 2008, it is really difficult to update an existing project. Instead, it is recommended to
simply create a new Visual Studio project based on an existing example. For Visual Studio 2008 use the "vcproj"
files. For Visual Studio 2010 and 2012 use the "vcxproj" files.

1. choose a relevant starting point, e.g., the "dummy" example project

2. copy it to the folder your old project was in, rename it

3. open it in a text editor such as "sublime text 2"

4. do a find/replace for all instances of the text "dummy" changing it to your object's name

5. open the Visual Studio project and build you can choose either "Win32" or "x64" from the platform drop-down
menu in the IDE

34.3 Changes to Code

34.3.1 Atoms

Any assumptions in your code about the size of a t_atom or the size of its members should be reviewed. When
setting or getting values to and from atoms you should use the types t_atom_long and t_atom_float as appropriate.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

34.4 Common Scenarios 139

34.3.2 Return Values

All methods which return a value must return a pointer-sized value, e.g., t_ptr_int, t_ptr_uint, t_max_err, etc.

34.3.3 File Code

File access in Max involves several areas subject to either required or suggested update.
A path in Max has traditionally been represented with a short int; it is recommened to now use the new t_filepath
type.
File types in Max are represented using four char codes. Traditionally these have been defined using variables of
type "long", which is now problematic. This is a 4-byte type but the long on the Mac for x64 is 8-bytes. These must
be updated to use the new t_fourcc type.

34.3.4 Miscellaneous Gotchas

Look for any ld or lu strings in sprintf() or related formatting functions.

34.4 Common Scenarios

34.4.1 "Long" integers

One of biggest areas we've had to address is the use of the long datatype. The reason for this is that under 64bit
windows a long integer is 32 bits and under 64bit OS X (and Unix), a long is a 64 bit integer.
To assist in this process, we have a the new data types documented above. We'll distinguis these from what we are
calling a "platform long".
This platform long discrepancy can lead to all sorts of problems which are outlined with a brief statement of the
problem scenario, and our recommended fix with types:
Problem: long integers as A_LONG/A_DEFLONG method arguments (this includes your object construc-
tors)
Solution: type your A_LONG/A_DEFLONG methods' function signatures to use the t_atom_long in place of long
Problem: long integers as A_CANT method arguments called only through object_method()
Solution: either redefine your A_CANT method's arguments to t_atom_long, or define your type as A_DIRECT, and
make use of the object_method_direct() macro, passing in a function prototype to the macro (also see under floating
point how this is required for anything which previously was A_CANT with floating point values). Technically many
of these will still work properly due to the nature of how integers are passed on the stack under x64, without any
change, it is still best practice.
Problem: long integers being used to store pointers as integer values either for pointer arithmetic, at-
tributes, or other situations.
Solution: use t_atom_long or even better t_ptr_uint (for pointer sized unsigned integer) or the actual pointer type.
Problem: long integers as four character codes for filetypes (t_fourcc) which applies to locatefile_extended
and path functions and friends
Solution: Use t_foucc inplace of long, for anywhere you are using filetype codes.
Problem: long integers as return values for functions called via object_method()
Solution: These should always return a t_atom_long or other pointer sized integer
Problem: long integers passed as pointers into functions like dictionary_getlong() which are now proto-
typed to take a t_atom_long ∗

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

140 Appendix: Updating Externals for Max 6.1 (x64 architecture)

Solution: Use a t_atom_long value, and pass a pointer to it. A cast from a platform long ∗to a t_atom_long ∗ is not
safe.
Problem: long integers for performing bitwise manipulation of 32bit floating point values including
byteswapping
Solution: Use t_int32/t_uint32
There are many cases where it is safe to use long integers, and we have continued to use them in our code. Below
are the scenarios where they are okay and in several cases required. This might provide some confusion at some
points, but hopefully it makes the porting process a little bit easier, allowing more code to remain unchanged.

• Attributes defined as _sym_long should remain a platform long. If you need to have a t_atom_long attribute,
you will need to use the new atom_long attribute type. This is probably the most confusing aspect of porting
to 64bit and a very real ambiguity of the word "long". Unfortunately, having to balance the difficulties of porting
with the clarity of API, this is something we felt necessary to do.

• Attribute getters/setters should still use the long type for ac. this is especially important for getters which are
passed a pointer to a platform long in the ac value.

• A_GIMME methods may still use the long type for ac without issues

34.4.2 Floating point values

For A_FLOAT/A_DEFFLOAT function signatures, you should always use double as is currently recommended in
the Max SDK. You should not use the new t_atom_float dataype. (this includes your object constructors)
For A_CANT functions with floating point arguments that currently use object_method(). You will need to use
object_method_direct() or pass in pointers to the floating point values (which is safe as it is a pointer sized integer).
It is no longer possible to pass floats through object_method() or the many functions like it (linklist_methodall(),
hashtab_methodall(), etc.)
Attributes are already defined in terms of their bitsize float32 or float 64. If you wish for your attribute to make use of
the new atom support for double preceision. You will want to change your struct definition, as well as your attribute
constructor to be a double (_sym_float64). There isn't currently a t_atom_float attribute type like we've added for
long.

34.4.3 Deprecated Apple types

like Byte/Boolean/Point/etc
Use the t_byte/t_bool/t_point/etc types instead.

34.5 Additional Miscellaneous Changes

The old 32-bit 'dsp' (and perform) methods are no longer supported as of Max 6.1. They must be updated as per
Updating MSP Externals for 64-bit Audio Processing .

34.6 Additional Resources

• http://www.viva64.com/en/a/0004/

• https://developer.apple.com/library/mac/#documentation/Cocoa/Conceptual/←-
Cocoa64BitGuide/64BitChangesCocoa/64BitChangesCocoa.html

• https://developer.apple.com/library/mac/#documentation/Carbon/Conceptual/←-
Carbon64BitGuide/OtherAPIChanges/OtherAPIChanges.html

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

34.6 Additional Resources 141

• http://msdn.microsoft.com/en-us/magazine/cc300794.aspx

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

142 Appendix: Updating Externals for Max 6.1 (x64 architecture)

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 35

Appendix: SDK changes for Max 7

35.1 Using ext_main for Entry Point

Prior to Max 7 the entry point for externals was the main() function exported from the dynamic library you create.
Beginning with Max 7 the entry point for externals is called ext_main(). This addresses compatibility problems
with various newer compilers and frees us from the constraints enforced for main() as the standard entry point for
programs.
Objects that do no not define ext_main() will still be loaded using the older main(). Support for ext_main() is also
present in Max 6.1.9.

35.2 Support for Max 7 UI Object Styles

Max 7 introduces the concept of styles which determine the appearance of UI objects. For attributes of your U←-
I object to map to colors or attributes of a style you need to add the required attribute properties in your class
definition.
See the section on Styles for more information.
144 Appendix: SDK changes for Max 7

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

Chapter 36

Module Documentation

36.1 Attributes

An attribute of an object is a setting or property that tells the object how to do its job.

Data Structures

• struct t_attr
Common attr struct.

Macros

• #define CLASS_ATTR_CHAR(c, attrname, flags, structname, structmember)

Create a char attribute and add it to a Max class.
• #define CLASS_ATTR_LONG(c, attrname, flags, structname, structmember)
Create a t_atom_long integer attribute and add it to a Max class.
• #define CLASS_ATTR_ATOM_LONG(c, attrname, flags, structname, structmember)
Create a t_atom_long integer attribute and add it to a Max class.
• #define CLASS_ATTR_INT32(c, attrname, flags, structname, structmember)
Create a t_int32 integer attribute and add it to a Max class.
• #define CLASS_ATTR_FLOAT(c, attrname, flags, structname, structmember)
Create a 32-bit float attribute and add it to a Max class.
• #define CLASS_ATTR_DOUBLE(c, attrname, flags, structname, structmember)
Create a 64-bit float attribute and add it to a Max class.
• #define CLASS_ATTR_SYM(c, attrname, flags, structname, structmember)
Create a t_symbol∗ attribute and add it to a Max class.
• #define CLASS_ATTR_ATOM(c, attrname, flags, structname, structmember)
Create a t_atom attribute and add it to a Max class.
• #define CLASS_ATTR_OBJ(c, attrname, flags, structname, structmember)
Create a t_object∗ attribute and add it to a Max class.
• #define CLASS_ATTR_CHAR_ARRAY(c, attrname, flags, structname, structmember, size)
Create an array-of-chars attribute of fixed length, and add it to a Max class.
• #define CLASS_ATTR_LONG_ARRAY(c, attrname, flags, structname, structmember, size)
Create an array-of-long-integers attribute of fixed length, and add it to a Max class.
• #define CLASS_ATTR_ATOM_LONG_ARRAY(c, attrname, flags, structname, structmember, size)
Create an array-of-t_atom_long-integers attribute of fixed length, and add it to a Max class.
• #define CLASS_ATTR_FLOAT_ARRAY(c, attrname, flags, structname, structmember, size)
146 Module Documentation

Create an array-of-32bit-floats attribute of fixed length, and add it to a Max class.

• #define CLASS_ATTR_DOUBLE_ARRAY(c, attrname, flags, structname, structmember, size)
Create an array-of-64bit-floats attribute of fixed length, and add it to a Max class.
• #define CLASS_ATTR_SYM_ARRAY(c, attrname, flags, structname, structmember, size)
Create an array-of-symbols attribute of fixed length, and add it to a Max class.
• #define CLASS_ATTR_ATOM_ARRAY(c, attrname, flags, structname, structmember, size)
Create an array-of-atoms attribute of fixed length, and add it to a Max class.
• #define CLASS_ATTR_OBJ_ARRAY(c, attrname, flags, structname, structmember, size)
Create an array-of-objects attribute of fixed length, and add it to a Max class.
• #define CLASS_ATTR_CHAR_VARSIZE(c, attrname, flags, structname, structmember, sizemember, max-
size)
Create an array-of-chars attribute of variable length, and add it to a Max class.
• #define CLASS_ATTR_LONG_VARSIZE(c, attrname, flags, structname, structmember, sizemember, max-
size)
Create an array-of-long-integers attribute of variable length, and add it to a Max class.
• #define CLASS_ATTR_FLOAT_VARSIZE(c, attrname, flags, structname, structmember, sizemember, max-
size)
Create an array-of-32bit-floats attribute of variable length, and add it to a Max class.
• #define CLASS_ATTR_DOUBLE_VARSIZE(c, attrname, flags, structname, structmember, sizemember,
maxsize)
Create an array-of-64bit-floats attribute of variable length, and add it to a Max class.
• #define CLASS_ATTR_SYM_VARSIZE(c, attrname, flags, structname, structmember, sizemember, maxsize)
Create an array-of-symbols attribute of variable length, and add it to a Max class.
• #define CLASS_ATTR_ATOM_VARSIZE(c, attrname, flags, structname, structmember, sizemember, max-
size)
Create an array-of-atoms attribute of variable length, and add it to a Max class.
• #define CLASS_ATTR_OBJ_VARSIZE(c, attrname, flags, structname, structmember, sizemember, maxsize)
Create an array-of-objects attribute of variable length, and add it to a Max class.
• #define STRUCT_ATTR_CHAR(c, flags, structname, structmember)
Create a char attribute and add it to a Max class.
• #define STRUCT_ATTR_LONG(c, flags, structname, structmember)
Create a long integer attribute and add it to a Max class.
• #define STRUCT_ATTR_ATOM_LONG(c, flags, structname, structmember)
Create a t_atom_long integer attribute and add it to a Max class.
• #define STRUCT_ATTR_FLOAT(c, flags, structname, structmember)
Create a 32bit float attribute and add it to a Max class.
• #define STRUCT_ATTR_DOUBLE(c, flags, structname, structmember)
Create a 64bit float attribute and add it to a Max class.
• #define STRUCT_ATTR_SYM(c, flags, structname, structmember)
Create a t_symbol∗ attribute and add it to a Max class.
• #define STRUCT_ATTR_ATOM(c, flags, structname, structmember)
Create a t_atom attribute and add it to a Max class.
• #define STRUCT_ATTR_OBJ(c, flags, structname, structmember)
Create a t_object∗ attribute and add it to a Max class.
• #define STRUCT_ATTR_CHAR_ARRAY(c, flags, structname, structmember, size)
Create an array-of-chars attribute of fixed length, and add it to a Max class.
• #define STRUCT_ATTR_LONG_ARRAY(c, flags, structname, structmember, size)
Create an array-of-long-integers attribute of fixed length, and add it to a Max class.
• #define STRUCT_ATTR_FLOAT_ARRAY(c, flags, structname, structmember, size)
Create an array-of-32bit-floats attribute of fixed length, and add it to a Max class.
• #define STRUCT_ATTR_DOUBLE_ARRAY(c, flags, structname, structmember, size)

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 147

Create an array-of-64bit-floats attribute of fixed length, and add it to a Max class.

• #define STRUCT_ATTR_SYM_ARRAY(c, flags, structname, structmember, size)
Create an array-of-symbols attribute of fixed length, and add it to a Max class.
• #define STRUCT_ATTR_ATOM_ARRAY(c, flags, structname, structmember, size)
Create an array-of-atoms attribute of fixed length, and add it to a Max class.
• #define STRUCT_ATTR_OBJ_ARRAY(c, flags, structname, structmember, size)
Create an array-of-objects attribute of fixed length, and add it to a Max class.
• #define STRUCT_ATTR_CHAR_VARSIZE(c, flags, structname, structmember, sizemember, maxsize)
Create an array-of-chars attribute of variable length, and add it to a Max class.
• #define STRUCT_ATTR_LONG_VARSIZE(c, flags, structname, structmember, sizemember, maxsize)
Create an array-of-long-integers attribute of variable length, and add it to a Max class.
• #define STRUCT_ATTR_FLOAT_VARSIZE(c, flags, structname, structmember, sizemember, maxsize)
Create an array-of-32bit-floats attribute of variable length, and add it to a Max class.
• #define STRUCT_ATTR_DOUBLE_VARSIZE(c, flags, structname, structmember, sizemember, maxsize)
Create an array-of-64bit-floats attribute of variable length, and add it to a Max class.
• #define STRUCT_ATTR_SYM_VARSIZE(c, flags, structname, structmember, sizemember, maxsize)
Create an array-of-symbols attribute of variable length, and add it to a Max class.
• #define STRUCT_ATTR_ATOM_VARSIZE(c, flags, structname, structmember, sizemember, maxsize)
Create an array-of-atoms attribute of variable length, and add it to a Max class.
• #define STRUCT_ATTR_OBJ_VARSIZE(c, flags, structname, structmember, sizemember, maxsize)
Create an array-of-objects attribute of variable length, and add it to a Max class.
• #define OBJ_ATTR_CHAR(x, attrname, flags, val)
Create an instance-local char attribute and add it to a Max class.
• #define OBJ_ATTR_LONG(x, attrname, flags, val)
Create an instance-local long integer attribute and add it to a Max class.
• #define OBJ_ATTR_FLOAT(x, attrname, flags, val)
Create an instance-local 32bit float attribute and add it to a Max class.
• #define OBJ_ATTR_DOUBLE(x, attrname, flags, val)
Create an instance-local 64bit float attribute and add it to a Max class.
• #define OBJ_ATTR_SYM(x, attrname, flags, val)
Create an instance-local t_symbol∗ attribute and add it to a Max class.
• #define OBJ_ATTR_ATOM(x, attrname, flags, val)
Create an instance-local t_atom attribute and add it to a Max class.
• #define OBJ_ATTR_OBJ(x, attrname, flags, val)
Create an instance-local t_object∗ attribute and add it to a Max class.
• #define OBJ_ATTR_CHAR_ARRAY(x, attrname, flags, count, vals)
Create an instance-local array-of-chars attribute of fixed length, and add it to the object.
• #define OBJ_ATTR_LONG_ARRAY(x, attrname, flags, count, vals)
Create an instance-local array-of-long-integers attribute of fixed length, and add it to the object.
• #define OBJ_ATTR_FLOAT_ARRAY(x, attrname, flags, count, vals)
Create an instance-local array-of-32bit-floats attribute of fixed length, and add it to the object.
• #define OBJ_ATTR_DOUBLE_ARRAY(x, attrname, flags, count, vals)
Create an instance-local array-of-64bit-floats attribute of fixed length, and add it to the object.
• #define OBJ_ATTR_SYM_ARRAY(x, attrname, flags, count, vals)
Create an instance-local array-of-symbols attribute of fixed length, and add it to the object.
• #define OBJ_ATTR_ATOM_ARRAY
Create an instance-local array-of-atoms attribute of fixed length, and add it to the object.
• #define OBJ_ATTR_OBJ_ARRAY(x, attrname, flags, count, vals)
Create an instance-local array-of-objects attribute of fixed length, and add it to the object.
• #define CLASS_ATTR_ACCESSORS(c, attrname, getter, setter)
Specify custom accessor methods for an attribute.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

148 Module Documentation

• #define CLASS_ATTR_ADD_FLAGS(c, attrname, flags)

Add flags to an attribute.
• #define CLASS_ATTR_REMOVE_FLAGS(c, attrname, flags)
Remove flags from an attribute.
• #define CLASS_ATTR_FILTER_MIN(c, attrname, minval)
Add a filter to the attribute to limit the lower bound of a value.
• #define CLASS_ATTR_FILTER_MAX(c, attrname, maxval)
Add a filter to the attribute to limit the upper bound of a value.
• #define CLASS_ATTR_FILTER_CLIP(c, attrname, minval, maxval)
Add a filter to the attribute to limit both the lower and upper bounds of a value.
• #define CLASS_ATTR_ALIAS(c, attrname, aliasname)
Create a new attribute that is an alias of an existing attribute.
• #define CLASS_ATTR_DEFAULT(c, attrname, flags, parsestr)
Add a new attribute to the specified attribute to specify a default value.
• #define CLASS_ATTR_SAVE(c, attrname, flags)
Add a new attribute to the specified attribute to indicate that the specified attribute should be saved with the patcher.
• #define CLASS_ATTR_SELFSAVE(c, attrname, flags)
Add a new attribute to the specified attribute to indicate that it is saved by the object (so it does not appear in italics in
the inspector).
• #define CLASS_ATTR_DEFAULT_SAVE(c, attrname, flags, parsestr)
A convenience wrapper for both CLASS_ATTR_DEFAULT and CLASS_ATTR_SAVE.
• #define CLASS_ATTR_DEFAULTNAME(c, attrname, flags, parsestr)
Add a new attribute to the specified attribute to specify a default value, based on Max's Object Defaults.
• #define CLASS_ATTR_DEFAULTNAME_SAVE(c, attrname, flags, parsestr)
A convenience wrapper for both CLASS_ATTR_DEFAULTNAME and CLASS_ATTR_SAVE.
• #define CLASS_ATTR_MIN(c, attrname, flags, parsestr)
Add a new attribute to the specified attribute to specify a lower range.
• #define CLASS_ATTR_MAX(c, attrname, flags, parsestr)
Add a new attribute to the specified attribute to specify an upper range.
• #define CLASS_ATTR_PAINT(c, attrname, flags)
Add a new attribute indicating that any changes to the specified attribute will trigger a call to the object's paint method.
• #define CLASS_ATTR_DEFAULT_PAINT(c, attrname, flags, parsestr)
A convenience wrapper for both CLASS_ATTR_DEFAULT and CLASS_ATTR_PAINT.
• #define CLASS_ATTR_DEFAULT_SAVE_PAINT(c, attrname, flags, parsestr)
A convenience wrapper for CLASS_ATTR_DEFAULT, CLASS_ATTR_SAVE, and CLASS_ATTR_PAINT.
• #define CLASS_ATTR_DEFAULTNAME_PAINT(c, attrname, flags, parsestr)
A convenience wrapper for CLASS_ATTR_DEFAULTNAME, CLASS_ATTR_SAVE, and CLASS_ATTR_PAINT.
• #define CLASS_ATTR_DEFAULTNAME_SAVE_PAINT(c, attrname, flags, parsestr)
A convenience wrapper for CLASS_ATTR_DEFAULTNAME, CLASS_ATTR_SAVE, and CLASS_ATTR_PAINT.
• #define CLASS_ATTR_STYLE(c, attrname, flags, parsestr)
Add a new attribute to the specified attribute to specify an editor style for the Max inspector.
• #define CLASS_ATTR_LABEL(c, attrname, flags, labelstr)
Add a new attribute to the specified attribute to specify an a human-friendly label for the Max inspector.
• #define CLASS_ATTR_ENUM(c, attrname, flags, parsestr)
Add a new attribute to the specified attribute to specify a list of choices to display in a menu for the Max inspector.
• #define CLASS_ATTR_ENUMINDEX(c, attrname, flags, parsestr)
Add a new attribute to the specified attribute to specify a list of choices to display in a menu for the Max inspector.
• #define CLASS_ATTR_CATEGORY(c, attrname, flags, parsestr)
Add a new attribute to the specified attribute to specify a category to which the attribute is assigned in the Max
inspector.
• #define CLASS_ATTR_STYLE_LABEL(c, attrname, flags, stylestr, labelstr)

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 149

A convenience wrapper for CLASS_ATTR_STYLE, and CLASS_ATTR_LABEL.

• #define CLASS_ATTR_INVISIBLE(c, attrname, flags)
Add a new attribute to the specified attribute to flag an attribute as invisible to the Max inspector.
• #define CLASS_ATTR_ORDER(c, attrname, flags, parsestr)
Add a new attribute to the specified attribute to specify a default order in which to list attributes.
• #define CLASS_ATTR_BASIC(c, attrname, flags)
Add a new attribute to the specified attribute to specify that it should appear in the inspector's Basic tab.
• #define CLASS_METHOD_ATTR_PARSE(c, methodname, attrname, type, flags, parsestring)
Define and add attributes to class methods.
• #define CLASS_ATTR_LEGACYDEFAULT(c, legacyattrname, newattrname, flags, parsestr)
Add a new attribute to the specified attribute to specify a legacy default value.
• #define CLASS_ATTR_OBSOLETE(c, attrname, flags)
Add a new attribute to the specified attribute to flag it as obsolete.
• #define CLASS_ATTR_RENAMED(c, oldname, newname, flags)
Add a new attribute to the specified attribute to flag it as renamed.
• #define CLASS_ATTR_INTRODUCED(c, attrname, flags, versionstr)
Add a new attribute to the specified attribute to indicate in which version the attribute was introduced.
• #define CLASS_METHOD_OBSOLETE(c, methodname, flags)
Add a new attribute to the specified method to flag it as obsolete.
• #define CLASS_METHOD_RENAMED(c, oldname, newname, flags)
Add a new attribute to the specified method to flag a method as renamed.
• #define CLASS_METHOD_INTRODUCED(c, methodname, flags, versionstr)
Add a new attribute to the specified method to indicate in which version the method was introduced.
• #define OBJ_ATTR_DEFAULT(x, attrname, flags, parsestr)
An instance-attribute version of CLASS_ATTR_DEFAULT.
• #define OBJ_ATTR_SAVE(x, attrname, flags)
An instance-attribute version of CLASS_ATTR_SAVE.
• #define OBJ_ATTR_DEFAULT_SAVE(x, attrname, flags, parsestr)
An instance-attribute version of CLASS_ATTR_DEFAULT_SAVE.
• #define CLASS_STICKY_ATTR(c, name, flags, parsestr)
Create an attribute, and add it to all following attribute declarations.
• #define CLASS_STICKY_ATTR_CLEAR(c, name)
Close a CLASS_STICKY_ATTR block.
• #define CLASS_STICKY_METHOD(c, name, flags, parsestr)
Create an attribute, and add it to all following method declarations.
• #define CLASS_STICKY_METHOD_CLEAR(c, name)
Close a CLASS_STICKY_METHOD block.
• #define CLASS_ATTR_RGBA(c, attrname, flags, structname, structmember)
Create a color (t_jrgba) attribute and add it to a Max class.

Enumerations

• enum e_max_attrflags {
ATTR_FLAGS_NONE, ATTR_GET_OPAQUE, ATTR_SET_OPAQUE, ATTR_GET_OPAQUE_USER,
ATTR_SET_OPAQUE_USER }
Attribute flags.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

150 Module Documentation

Functions

• void ∗ object_attr_get (void ∗x, t_symbol ∗attrname)

Returns the pointer to an attribute, given its name.
• method object_attr_method (void ∗x, t_symbol ∗methodname, void ∗∗attr, long ∗get)
Returns the method of an attribute's get or set function, as well as a pointer to the attribute itself, from a message
name.
• long object_attr_usercanset (void ∗x, t_symbol ∗s)
Determines if an object's attribute can be set from the Max interface (i.e.
• long object_attr_usercanget (void ∗x, t_symbol ∗s)
Determines if the value of an object's attribute can be queried from the Max interface (i.e.
• void object_attr_getdump (void ∗x, t_symbol ∗s, long argc, t_atom ∗argv)
Forces a specified object's attribute to send its value from the object's dumpout outlet in the Max interface.
• t_max_err object_attr_setvalueof (void ∗x, t_symbol ∗s, long argc, t_atom ∗argv)
Sets the value of an object's attribute.
• t_max_err object_addattr (void ∗x, t_object ∗attr)
Attaches an attribute directly to an object.
• t_max_err object_deleteattr (void ∗x, t_symbol ∗attrsym)
Detach an attribute from an object that was previously attached with object_addattr().
• t_max_err object_chuckattr (void ∗x, t_symbol ∗attrsym)
Detach an attribute from an object that was previously attached with object_addattr().
• long attr_args_offset (short ac, t_atom ∗av)
Determines the point in an atom list where attribute arguments begin.
• void attr_args_process (void ∗x, short ac, t_atom ∗av)
Takes an atom list and properly set any attributes described within.
• t_object ∗ attribute_new (C74_CONST char ∗name, t_symbol ∗type, long flags, method mget, method mset)
Create a new attribute.
• t_object ∗ attr_offset_new (C74_CONST char ∗name, C74_CONST t_symbol ∗type, long flags, C74_CON←-
ST method mget, C74_CONST method mset, long offset)
Create a new attribute.
• t_object ∗ attr_offset_array_new (C74_CONST char ∗name, t_symbol ∗type, long size, long flags, method
mget, method mset, long offsetcount, long offset)
Create a new attribute.
• t_atom_long object_attr_getlong (void ∗x, t_symbol ∗s)
Retrieves the value of an attribute, given its parent object and name.
• t_max_err object_attr_setlong (void ∗x, t_symbol ∗s, t_atom_long c)
Sets the value of an attribute, given its parent object and name.
• t_atom_float object_attr_getfloat (void ∗x, t_symbol ∗s)
Retrieves the value of an attribute, given its parent object and name.
• t_max_err object_attr_setfloat (void ∗x, t_symbol ∗s, t_atom_float c)
Sets the value of an attribute, given its parent object and name.
• t_symbol ∗ object_attr_getsym (void ∗x, t_symbol ∗s)
Retrieves the value of an attribute, given its parent object and name.
• t_max_err object_attr_setsym (void ∗x, t_symbol ∗s, t_symbol ∗c)
Sets the value of an attribute, given its parent object and name.
• long object_attr_getlong_array (void ∗x, t_symbol ∗s, long max, t_atom_long ∗vals)
Retrieves the value of an attribute, given its parent object and name.
• t_max_err object_attr_setlong_array (void ∗x, t_symbol ∗s, long count, t_atom_long ∗vals)
Sets the value of an attribute, given its parent object and name.
• long object_attr_getchar_array (void ∗x, t_symbol ∗s, long max, t_uint8 ∗vals)
Retrieves the value of an attribute, given its parent object and name.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 151

• t_max_err object_attr_setchar_array (void ∗x, t_symbol ∗s, long count, C74_CONST t_uint8 ∗vals)
Sets the value of an attribute, given its parent object and name.
• long object_attr_getfloat_array (void ∗x, t_symbol ∗s, long max, float ∗vals)
Retrieves the value of an attribute, given its parent object and name.
• t_max_err object_attr_setfloat_array (void ∗x, t_symbol ∗s, long count, float ∗vals)
Sets the value of an attribute, given its parent object and name.
• long object_attr_getdouble_array (void ∗x, t_symbol ∗s, long max, double ∗vals)
Retrieves the value of an attribute, given its parent object and name.
• t_max_err object_attr_setdouble_array (void ∗x, t_symbol ∗s, long count, double ∗vals)
Sets the value of an attribute, given its parent object and name.
• long object_attr_getsym_array (void ∗x, t_symbol ∗s, long max, t_symbol ∗∗vals)
Retrieves the value of an attribute, given its parent object and name.
• t_max_err object_attr_setsym_array (void ∗x, t_symbol ∗s, long count, t_symbol ∗∗vals)
Sets the value of an attribute, given its parent object and name.
• t_max_err attr_addfilterset_clip (void ∗x, double min, double max, long usemin, long usemax)
Attaches a clip filter to an attribute.
• t_max_err attr_addfilterset_clip_scale (void ∗x, double scale, double min, double max, long usemin, long
usemax)
Attaches a clip/scale filter to an attribute.
• t_max_err attr_addfilterget_clip (void ∗x, double min, double max, long usemin, long usemax)
Attaches a clip filter to an attribute.
• t_max_err attr_addfilterget_clip_scale (void ∗x, double scale, double min, double max, long usemin, long
usemax)
Attaches a clip/scale filter to an attribute.
• t_max_err attr_addfilter_clip (void ∗x, double min, double max, long usemin, long usemax)
Attaches a clip filter to an attribute.
• t_max_err attr_addfilter_clip_scale (void ∗x, double scale, double min, double max, long usemin, long use-
max)
Attaches a clip/scale filter to an attribute.
• t_max_err attr_addfilterset_proc (void ∗x, method proc)
Attaches a custom filter method to an attribute.
• t_max_err attr_addfilterget_proc (void ∗x, method proc)
Attaches a custom filter method to an attribute.
• void attr_args_dictionary (t_dictionary ∗x, short ac, t_atom ∗av)
Create a dictionary of attribute-name, attribute-value pairs from an array of atoms containing an attribute definition
list.
• void attr_dictionary_process (void ∗x, t_dictionary ∗d)
Set attributes for an object that are defined in a dictionary.
• void attr_dictionary_check (void ∗x, t_dictionary ∗d)
Check that a dictionary only contains values for existing attributes of an object.
• t_max_err object_attr_setparse (t_object ∗x, t_symbol ∗s, C74_CONST char ∗parsestr)
Set an attribute value with one or more atoms parsed from a C-string.
• void ∗ object_new_parse (t_symbol ∗name_space, t_symbol ∗classname, C74_CONST char ∗parsestr)
Create a new object with one or more atoms parsed from a C-string.
• t_max_err object_attr_getjrgba (void ∗ob, t_symbol ∗s, t_jrgba ∗c)
Retrieves the value of a color attribute, given its parent object and name.
• t_max_err object_attr_setjrgba (void ∗ob, t_symbol ∗s, t_jrgba ∗c)
Sets the value of a color attribute, given its parent object and name.
• t_max_err object_attr_get_rect (t_object ∗o, t_symbol ∗name, t_rect ∗rect)
Gets the value of a t_rect attribute, given its parent object and name.
• t_max_err object_attr_set_rect (t_object ∗o, t_symbol ∗name, t_rect ∗rect)

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

152 Module Documentation

Sets the value of a t_rect attribute, given its parent object and name.
• void object_attr_set_xywh (t_object ∗o, t_symbol ∗attr, double x, double y, double w, double h)
Sets the value of a t_rect attribute, given its parent object and name.
• t_max_err object_attr_getpt (t_object ∗o, t_symbol ∗name, t_pt ∗pt)
Gets the value of a t_pt attribute, given its parent object and name.
• t_max_err object_attr_setpt (t_object ∗o, t_symbol ∗name, t_pt ∗pt)
Sets the value of a t_pt attribute, given its parent object and name.
• t_max_err object_attr_getsize (t_object ∗o, t_symbol ∗name, t_size ∗size)
Gets the value of a t_size attribute, given its parent object and name.
• t_max_err object_attr_setsize (t_object ∗o, t_symbol ∗name, t_size ∗size)
Sets the value of a t_size attribute, given its parent object and name.
• t_max_err object_attr_getcolor (t_object ∗b, t_symbol ∗attrname, t_jrgba ∗prgba)
Gets the value of a t_jrgba attribute, given its parent object and name.
• t_max_err object_attr_setcolor (t_object ∗b, t_symbol ∗attrname, t_jrgba ∗prgba)
Sets the value of a t_jrgba attribute, given its parent object and name.

36.1.1 Detailed Description

An attribute of an object is a setting or property that tells the object how to do its job.
For example, the metro object has an interval attribute that tells it how fast to run.
Attributes are similar to methods, except that the attributes have a state. Attributes are themselves objects, and they
share a common interface for getting and setting values.
An attribute is most typically added to the class definition of another object during it's class initialization or ext_←-
main() function. Most typically, this attribute's value will be stored in an instance's struct, and thus it will serve as a
property of that instance of the object.
Attributes can, however, be declared as 'class static'. This means that the property is shared by all instances of the
class, and the value is stored as a shared (static) variable.
Additionally, Max 5 has introduced the notion of 'instance attributes' (also called 'object attributes'). Instance at-
tributes are the creation of an attribute object, and then adding it to one specific instance of another class.
Finally, because attributes themselves are Max objects they too can possess attributes. These 'attributes of at-
tributes' are used in Max to do things like specify a range of values for an attribute, give an attribute human friendly
caption, or determine to what category an attribute should belong in the inspector.
The easiest and most common way of working with attributes is to use the provided macros. These macros simplify
the process of creating a new attribute object, setting any attributes of the attribute, and binding it to an object class
or an object instance.

36.1.2 Setting and Getting Attribute Values

By default, Max provides standard attribute accessors. These are the functions the get or set the attribute value in
the object's struct. If you need to define a custom accessor, you can specify this information using the CLASS_A←-
TTR_ACCESSORS macro.

36.1.2.1 Writing a custom Attribute Getter

If you need to define a custom accessor, it should have a prototype and form comparable to the following custom
getter:

t_max_err foo_myval_get(t_foo *x, void *attr, long *ac, t_atom **av)

{
if ((*ac)&&(*av)) {
//memory passed in, use it

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 153

} else {
//otherwise allocate memory
*ac = 1;
if (!(*av = getbytes(sizeof(t_atom)*(*ac)))) {
*ac = 0;
return MAX_ERR_OUT_OF_MEM;
}
}
atom_setfloat(*av,x->myval);

return MAX_ERR_NONE;
}

Note that getters require memory to be allocated, if there is not memory passed into the getter. Also the attr
argument is the class' attribute object and can be queried using object_method for things like the attribute flags,
names, filters, etc..

36.1.2.2 Writing a custom Attribute Setter

If you need to define a custom accessor, it should have a prototype and form comparable to the following custom
setter:

t_max_err foo_myval_set(t_foo *x, void *attr, long ac, t_atom *av)

{
if (ac&&av) {
x->myval = atom_getfloat(av);
} else {
// no args, set to zero
x->myval = 0;
}
return MAX_ERR_NONE;
}

36.1.3 Attribute Notificaton

Although the subject of object registration and notification is covered elsewhere, it bears noting that attributes of all
types will, if registered, automatically send notifications to all attached client objects each time the attribute's value
is set.

36.1.4 Macro Definition Documentation

36.1.4.1 #define CLASS_ATTR_ACCESSORS( c, attrname, getter, setter )

Specify custom accessor methods for an attribute.

If you specify a non-NULL value for the setter or getter, then the function you specify will be called to set or get the
attribute's value rather than using the built-in accessor.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
getter An appropriate getter method as discussed in Setting and Getting Attribute Values, or NULL
to use the default getter.
setter An appropriate setter method as discussed in Setting and Getting Attribute Values, or NULL
to use the default setter.

36.1.4.2 #define CLASS_ATTR_ADD_FLAGS( c, attrname, flags )

Add flags to an attribute.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

154 Module Documentation

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to add to this attribute, as defined in e_max_attrflags.

36.1.4.3 #define CLASS_ATTR_ALIAS( c, attrname, aliasname )

Create a new attribute that is an alias of an existing attribute.

Parameters
c The class pointer.
attrname The name of the actual attribute as a C-string.
aliasname The name of the new alias attribute.

36.1.4.4 #define CLASS_ATTR_ATOM( c, attrname, flags, structname, structmember )

Create a t_atom attribute and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.5 #define CLASS_ATTR_ATOM_ARRAY( c, attrname, flags, structname, structmember, size )

Create an array-of-atoms attribute of fixed length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of items in the t_atom array.

36.1.4.6 #define CLASS_ATTR_ATOM_LONG( c, attrname, flags, structname, structmember )

Create a t_atom_long integer attribute and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 155

structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.7 #define CLASS_ATTR_ATOM_LONG_ARRAY( c, attrname, flags, structname, structmember, size )

Create an array-of-t_atom_long-integers attribute of fixed length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of longs in the array.

36.1.4.8 #define CLASS_ATTR_ATOM_VARSIZE( c, attrname, flags, structname, structmember, sizemember, maxsize )

Create an array-of-atoms attribute of variable length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the t_atom array at any given moment.
maxsize The maximum number of items in the t_atom array, i.e. the number of members allocated for
the array in the struct.

36.1.4.9 #define CLASS_ATTR_BASIC( c, attrname, flags )

Add a new attribute to the specified attribute to specify that it should appear in the inspector's Basic tab.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.

Referenced by jit_ob3d_setup().

36.1.4.10 #define CLASS_ATTR_CATEGORY( c, attrname, flags, parsestr )

Add a new attribute to the specified attribute to specify a category to which the attribute is assigned in the Max
inspector.
Categories are represented in the inspector as tabs. If the specified category does not exist then it will be created.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

156 Module Documentation

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

36.1.4.11 #define CLASS_ATTR_CHAR( c, attrname, flags, structname, structmember )

Create a char attribute and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.12 #define CLASS_ATTR_CHAR_ARRAY( c, attrname, flags, structname, structmember, size )

Create an array-of-chars attribute of fixed length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of chars in the array.

36.1.4.13 #define CLASS_ATTR_CHAR_VARSIZE( c, attrname, flags, structname, structmember, sizemember, maxsize )

Create an array-of-chars attribute of variable length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the char array at any given moment.
maxsize The maximum number of items in the char array, i.e. the number of members allocated for
the array in the struct.

36.1.4.14 #define CLASS_ATTR_DEFAULT( c, attrname, flags, parsestr )

Add a new attribute to the specified attribute to specify a default value.

The default value will be automatically set when the object is created only if your object uses a dictionary constructor
with the CLASS_FLAG_NEWDICTIONARY flag.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 157

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

36.1.4.15 #define CLASS_ATTR_DEFAULT_PAINT( c, attrname, flags, parsestr )

A convenience wrapper for both CLASS_ATTR_DEFAULT and CLASS_ATTR_PAINT.

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

See also

CLASS_ATTR_DEFAULT
CLASS_ATTR_PAINT

36.1.4.16 #define CLASS_ATTR_DEFAULT_SAVE( c, attrname, flags, parsestr )

A convenience wrapper for both CLASS_ATTR_DEFAULT and CLASS_ATTR_SAVE.

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

See also

CLASS_ATTR_DEFAULT
CLASS_ATTR_SAVE

36.1.4.17 #define CLASS_ATTR_DEFAULT_SAVE_PAINT( c, attrname, flags, parsestr )

A convenience wrapper for CLASS_ATTR_DEFAULT, CLASS_ATTR_SAVE, and CLASS_ATTR_PAINT.

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

See also

CLASS_ATTR_DEFAULT
CLASS_ATTR_PAINT
CLASS_ATTR_SAVE

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

158 Module Documentation

36.1.4.18 #define CLASS_ATTR_DEFAULTNAME( c, attrname, flags, parsestr )

Add a new attribute to the specified attribute to specify a default value, based on Max's Object Defaults.
If a value is present in Max's Object Defaults, then that value will be used as the default value. Otherwise, use the
default value specified here. The default value will be automatically set when the object is created only if your object
uses a dictionary constructor with the CLASS_FLAG_NEWDICTIONARY flag.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

36.1.4.19 #define CLASS_ATTR_DEFAULTNAME_PAINT( c, attrname, flags, parsestr )

A convenience wrapper for CLASS_ATTR_DEFAULTNAME, CLASS_ATTR_SAVE, and CLASS_ATTR_PAINT.

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

See also

CLASS_ATTR_DEFAULTNAME
CLASS_ATTR_PAINT
CLASS_ATTR_SAVE

36.1.4.20 #define CLASS_ATTR_DEFAULTNAME_SAVE( c, attrname, flags, parsestr )

A convenience wrapper for both CLASS_ATTR_DEFAULTNAME and CLASS_ATTR_SAVE.

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

See also

CLASS_ATTR_DEFAULTNAME
CLASS_ATTR_SAVE

36.1.4.21 #define CLASS_ATTR_DEFAULTNAME_SAVE_PAINT( c, attrname, flags, parsestr )

A convenience wrapper for CLASS_ATTR_DEFAULTNAME, CLASS_ATTR_SAVE, and CLASS_ATTR_PAINT.

Parameters

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 159

c The class pointer.

attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

See also

CLASS_ATTR_DEFAULTNAME
CLASS_ATTR_PAINT
CLASS_ATTR_SAVE

36.1.4.22 #define CLASS_ATTR_DOUBLE( c, attrname, flags, structname, structmember )

Create a 64-bit float attribute and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.23 #define CLASS_ATTR_DOUBLE_ARRAY( c, attrname, flags, structname, structmember, size )

Create an array-of-64bit-floats attribute of fixed length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of doubles in the array.

36.1.4.24 #define CLASS_ATTR_DOUBLE_VARSIZE( c, attrname, flags, structname, structmember, sizemember,

maxsize )

Create an array-of-64bit-floats attribute of variable length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

160 Module Documentation

structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the double array at any given moment.
maxsize The maximum number of items in the double array, i.e. the number of members allocated for
the array in the struct.

36.1.4.25 #define CLASS_ATTR_ENUM( c, attrname, flags, parsestr )

Add a new attribute to the specified attribute to specify a list of choices to display in a menu for the Max inspector.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

Remarks

This macro automatically calls

1 CLASS_ATTR_STYLE(c,attrname,flags,"enum").

See also

CLASS_ATTR_ENUMINDEX

Referenced by jit_ob3d_setup().

36.1.4.26 #define CLASS_ATTR_ENUMINDEX( c, attrname, flags, parsestr )

Add a new attribute to the specified attribute to specify a list of choices to display in a menu for the Max inspector.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

Remarks

This macro automatically calls

1 CLASS_ATTR_STYLE(c,attrname,flags,"enumindex").

See also

CLASS_ATTR_ENUM

36.1.4.27 #define CLASS_ATTR_FILTER_CLIP( c, attrname, minval, maxval )

Add a filter to the attribute to limit both the lower and upper bounds of a value.
The limiting will be performed by the default attribute accessor.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 161

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
minval The maximum acceptable value to which the attribute will be limited.
maxval The maximum acceptable value to which the attribute will be limited.

See also

36.1.4.28 #define CLASS_ATTR_FILTER_MAX( c, attrname, maxval )

Add a filter to the attribute to limit the upper bound of a value.

The limiting will be performed by the default attribute accessor.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
maxval The maximum acceptable value to which the attribute will be limited.

See also

CLASS_ATTR_FILTER_MIN
CLASS_ATTR_FILTER_CLIP
CLASS_ATTR_MAX

36.1.4.29 #define CLASS_ATTR_FILTER_MIN( c, attrname, minval )

Add a filter to the attribute to limit the lower bound of a value.

The limiting will be performed by the default attribute accessor.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
minval The minimum acceptable value to which the attribute will be limited.

See also

CLASS_ATTR_FILTER_MAX
CLASS_ATTR_FILTER_CLIP
CLASS_ATTR_MIN

36.1.4.30 #define CLASS_ATTR_FLOAT( c, attrname, flags, structname, structmember )

Create a 32-bit float attribute and add it to a Max class.

Parameters

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

162 Module Documentation

c The class pointer.

attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.31 #define CLASS_ATTR_FLOAT_ARRAY( c, attrname, flags, structname, structmember, size )

Create an array-of-32bit-floats attribute of fixed length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of floats in the array.

36.1.4.32 #define CLASS_ATTR_FLOAT_VARSIZE( c, attrname, flags, structname, structmember, sizemember, maxsize )

Create an array-of-32bit-floats attribute of variable length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the float array at any given moment.
maxsize The maximum number of items in the float array, i.e. the number of members allocated for
the array in the struct.

36.1.4.33 #define CLASS_ATTR_INT32( c, attrname, flags, structname, structmember )

Create a t_int32 integer attribute and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.34 #define CLASS_ATTR_INTRODUCED( c, attrname, flags, versionstr )

Add a new attribute to the specified attribute to indicate in which version the attribute was introduced.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 163

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
versionstr A C-string, which will be parsed set the version number (e.g. "7.0.0").

36.1.4.35 #define CLASS_ATTR_INVISIBLE( c, attrname, flags )

Add a new attribute to the specified attribute to flag an attribute as invisible to the Max inspector.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.

36.1.4.36 #define CLASS_ATTR_LABEL( c, attrname, flags, labelstr )

Add a new attribute to the specified attribute to specify an a human-friendly label for the Max inspector.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
labelstr A C-string, which will be parsed into an array of atoms to set the initial value.

36.1.4.37 #define CLASS_ATTR_LEGACYDEFAULT( c, legacyattrname, newattrname, flags, parsestr )

Add a new attribute to the specified attribute to specify a legacy default value.
The default value will be automatically set when the object is created only if your object uses a dictionary constructor
with the CLASS_FLAG_NEWDICTIONARY flag.
Parameters
c The class pointer.
legacyattrname The name of the attribute.
newattrname The name of the attribute.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the legacy value, used by
jbox_processlegacydefaults()

36.1.4.38 #define CLASS_ATTR_LONG( c, attrname, flags, structname, structmember )

Create a t_atom_long integer attribute and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

164 Module Documentation

flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.39 #define CLASS_ATTR_LONG_ARRAY( c, attrname, flags, structname, structmember, size )

Create an array-of-long-integers attribute of fixed length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of longs in the array.

36.1.4.40 #define CLASS_ATTR_LONG_VARSIZE( c, attrname, flags, structname, structmember, sizemember, maxsize )

Create an array-of-long-integers attribute of variable length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the long array at any given moment.
maxsize The maximum number of items in the long array, i.e. the number of members allocated for
the array in the struct.

36.1.4.41 #define CLASS_ATTR_MAX( c, attrname, flags, parsestr )

Add a new attribute to the specified attribute to specify an upper range.

The values will not be automatically limited.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

See also

CLASS_ATTR_MIN
CLASS_ATTR_FILTER_MAX
CLASS_ATTR_FILTER_CLIP

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 165

36.1.4.42 #define CLASS_ATTR_MIN( c, attrname, flags, parsestr )

Add a new attribute to the specified attribute to specify a lower range.

The values will not be automatically limited.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

See also

CLASS_ATTR_MAX
CLASS_ATTR_FILTER_MAX
CLASS_ATTR_FILTER_CLIP

36.1.4.43 #define CLASS_ATTR_OBJ( c, attrname, flags, structname, structmember )

Create a t_object∗ attribute and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.44 #define CLASS_ATTR_OBJ_ARRAY( c, attrname, flags, structname, structmember, size )

Create an array-of-objects attribute of fixed length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of items in the t_object∗ array.

36.1.4.45 #define CLASS_ATTR_OBJ_VARSIZE( c, attrname, flags, structname, structmember, sizemember, maxsize )

Create an array-of-objects attribute of variable length, and add it to a Max class.

Parameters
c The class pointer.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

166 Module Documentation

attrname The name of this attribute as a C-string.

flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the t_object∗ array at any given moment.
maxsize The maximum number of items in the t_object∗ array, i.e. the number of members allocated
for the array in the struct.

36.1.4.46 #define CLASS_ATTR_OBSOLETE( c, attrname, flags )

Add a new attribute to the specified attribute to flag it as obsolete.

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.

36.1.4.47 #define CLASS_ATTR_ORDER( c, attrname, flags, parsestr )

Add a new attribute to the specified attribute to specify a default order in which to list attributes.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

Remarks

A value of zero indicates that there is no ordering. Ordering values begin at 1. For example:

1 CLASS_ATTR_ORDER(c, "firstattr", 0, "1");

2 CLASS_ATTR_ORDER(c, "secondattr", 0, "2");
3 CLASS_ATTR_ORDER(c, "thirdattr", 0, "3");

36.1.4.48 #define CLASS_ATTR_PAINT( c, attrname, flags )

Add a new attribute indicating that any changes to the specified attribute will trigger a call to the object's paint
method.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.

36.1.4.49 #define CLASS_ATTR_REMOVE_FLAGS( c, attrname, flags )

Remove flags from an attribute.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 167

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to remove from this attribute, as defined in e_max_attrflags.

36.1.4.50 #define CLASS_ATTR_RENAMED( c, oldname, newname, flags )

Add a new attribute to the specified attribute to flag it as renamed.

Parameters
c The class pointer.
oldname The name of the old attribute as a C-string.
newname The name of the new attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.

36.1.4.51 #define CLASS_ATTR_RGBA( c, attrname, flags, structname, structmember )

Create a color (t_jrgba) attribute and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.52 #define CLASS_ATTR_SAVE( c, attrname, flags )

Add a new attribute to the specified attribute to indicate that the specified attribute should be saved with the patcher.
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.

36.1.4.53 #define CLASS_ATTR_SELFSAVE( c, attrname, flags )

Add a new attribute to the specified attribute to indicate that it is saved by the object (so it does not appear in italics
in the inspector).
Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.

36.1.4.54 #define CLASS_ATTR_STYLE( c, attrname, flags, parsestr )

Add a new attribute to the specified attribute to specify an editor style for the Max inspector.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

168 Module Documentation

Available styles include

• "text" : a text editor

• "onoff" : a toggle switch

• "rgba" : a color chooser

• "enum" : a menu of available choices, whose symbol will be passed upon selection

• "enumindex" : a menu of available choices, whose index will be passed upon selection

• "rect" : a style for displaying and editing t_rect values

• "font" : a font chooser

• "file" : a file chooser dialog

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

36.1.4.55 #define CLASS_ATTR_STYLE_LABEL( c, attrname, flags, stylestr, labelstr )

A convenience wrapper for CLASS_ATTR_STYLE, and CLASS_ATTR_LABEL.

Parameters
c The class pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
stylestr A C-string that names the style for the attribute. See CLASS_ATTR_STYLE for the available
styles.
labelstr A C-string that names the category to which the attribute is assigned in the inspector.

See also

CLASS_ATTR_STYLE
CLASS_ATTR_LABEL

36.1.4.56 #define CLASS_ATTR_SYM( c, attrname, flags, structname, structmember )

Create a t_symbol∗ attribute and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 169

structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.57 #define CLASS_ATTR_SYM_ARRAY( c, attrname, flags, structname, structmember, size )

Create an array-of-symbols attribute of fixed length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of items in the t_symbol∗ array.

36.1.4.58 #define CLASS_ATTR_SYM_VARSIZE( c, attrname, flags, structname, structmember, sizemember, maxsize )

Create an array-of-symbols attribute of variable length, and add it to a Max class.

Parameters
c The class pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the t_symbol∗ array at any given moment.
maxsize The maximum number of items in the t_symbol∗ array, i.e. the number of members allocated
for the array in the struct.

36.1.4.59 #define CLASS_METHOD_ATTR_PARSE( c, methodname, attrname, type, flags, parsestring )

Define and add attributes to class methods.

Parameters
c The class pointer.
methodname The name of the existing method as a C-string.
attrname The name of the attribute to add as a C-string.
type The datatype of the attribute to be added.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestring A C-string, which will be parsed into an array of atoms to set the initial value.

Remarks

An example which makes a method invisible to users:

1 class_addmethod(c, (method)my_foo, "foo", 0);

2 CLASS_METHOD_ATTR_PARSE(c, "foo", "undocumented", gensym("long"), 0, "1");

Referenced by jit_ob3d_setup().

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

170 Module Documentation

36.1.4.60 #define CLASS_METHOD_INTRODUCED( c, methodname, flags, versionstr )

Add a new attribute to the specified method to indicate in which version the method was introduced.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 171

Parameters
c The class pointer.
methodname The name of the method as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
versionstr A C-string, which will be parsed set the version number (e.g. "7.0.0").

36.1.4.61 #define CLASS_METHOD_OBSOLETE( c, methodname, flags )

Add a new attribute to the specified method to flag it as obsolete.

Parameters
c The class pointer.
methodname The name of the method as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.

36.1.4.62 #define CLASS_METHOD_RENAMED( c, oldname, newname, flags )

Add a new attribute to the specified method to flag a method as renamed.

Parameters
c The class pointer.
oldname The name of the old method as a C-string.
newname The name of the new method as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.

36.1.4.63 #define CLASS_STICKY_ATTR( c, name, flags, parsestr )

Create an attribute, and add it to all following attribute declarations.

The block is closed by a call to CLASS_STICKY_ATTR_CLEAR.
Parameters
c The class pointer.
name The name of the new attribute to create as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

Remarks

The most common use of CLASS_STICKY_ATTR is for creating multiple attributes with the same category,
as in this example:
1 CLASS_STICKY_ATTR(c, "category", 0, "Foo");
2
3 CLASS_ATTR_DOUBLE(c, "bar", 0, t_myobject, x_bar);
4 CLASS_ATTR_LABEL(c, "bar", 0, "A Bar");
5
6 CLASS_ATTR_CHAR(c, "switch", 0, t_myobject, x_switch);
7 CLASS_ATTR_STYLE_LABEL(c, "switch", 0, "onoff", "Bar Switch");
8
9 CLASS_ATTR_DOUBLE(c, "flow", 0, t_myobject, x_flow);
10 CLASS_ATTR_LABEL(c, "flow", 0, "Flow Amount");
11
12 CLASS_STICKY_ATTR_CLEAR(c, "category");

See also

CLASS_STICKY_ATTR_CLEAR

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

172 Module Documentation

36.1.4.64 #define CLASS_STICKY_ATTR_CLEAR( c, name )

Close a CLASS_STICKY_ATTR block.

Parameters
c The class pointer.
name The name of the sticky attribute as a C-string.

See also

CLASS_STICKY_ATTR

36.1.4.65 #define CLASS_STICKY_METHOD( c, name, flags, parsestr )

Create an attribute, and add it to all following method declarations.

The block is closed by a call to CLASS_STICKY_METHOD_CLEAR.
Parameters
c The class pointer.
name The name of the new attribute to create as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

Remarks

The most common use of CLASS_STICKY_ATTR is for creating multiple attributes with the same category,
as in this example:
1 CLASS_STICKY_METHOD(c, "undocumented", 0, "1");
2
3 // add some methods here with class_addmethod()
4 // the undocumented attribute for methods means that the ref-page
5 // generator will ignore these methods.
6
7 CLASS_STICKY_METHOD_CLEAR(c, "undocumented");

See also

CLASS_STICKY_METHOD_CLEAR

36.1.4.66 #define CLASS_STICKY_METHOD_CLEAR( c, name )

Close a CLASS_STICKY_METHOD block.

Parameters
c The class pointer.
name The name of the sticky attribute as a C-string.

See also

CLASS_STICKY_METHOD

36.1.4.67 #define OBJ_ATTR_ATOM( x, attrname, flags, val )

Create an instance-local t_atom attribute and add it to a Max class.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 173

Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
val Pointer to the value.

36.1.4.68 #define OBJ_ATTR_ATOM_ARRAY

Create an instance-local array-of-atoms attribute of fixed length, and add it to the object.
Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
count The number of items in the t_atom array.
vals Pointer to the values.

36.1.4.69 #define OBJ_ATTR_CHAR( x, attrname, flags, val )

Create an instance-local char attribute and add it to a Max class.

Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
val Pointer to the value.

36.1.4.70 #define OBJ_ATTR_CHAR_ARRAY( x, attrname, flags, count, vals )

Create an instance-local array-of-chars attribute of fixed length, and add it to the object.
Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
count The number of items in the char array.
vals Pointer to the values.

36.1.4.71 #define OBJ_ATTR_DEFAULT( x, attrname, flags, parsestr )

An instance-attribute version of CLASS_ATTR_DEFAULT.

Parameters
x The t_object instance pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

174 Module Documentation

parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

See also

CLASS_ATTR_DEFAULT

36.1.4.72 #define OBJ_ATTR_DEFAULT_SAVE( x, attrname, flags, parsestr )

An instance-attribute version of CLASS_ATTR_DEFAULT_SAVE.

Parameters
x The t_object instance pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.
parsestr A C-string, which will be parsed into an array of atoms to set the initial value.

See also

CLASS_ATTR_DEFAULT_SAVE

36.1.4.73 #define OBJ_ATTR_DOUBLE( x, attrname, flags, val )

Create an instance-local 64bit float attribute and add it to a Max class.

Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
val Pointer to the value.

36.1.4.74 #define OBJ_ATTR_DOUBLE_ARRAY( x, attrname, flags, count, vals )

Create an instance-local array-of-64bit-floats attribute of fixed length, and add it to the object.
Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
count The number of items in the double array.
vals Pointer to the values.

36.1.4.75 #define OBJ_ATTR_FLOAT( x, attrname, flags, val )

Create an instance-local 32bit float attribute and add it to a Max class.

Parameters
x The object pointer.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 175

attrname The name of this attribute as a C-string.

flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
val Pointer to the value.

36.1.4.76 #define OBJ_ATTR_FLOAT_ARRAY( x, attrname, flags, count, vals )

Create an instance-local array-of-32bit-floats attribute of fixed length, and add it to the object.
Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
count The number of items in the float array.
vals Pointer to the values.

36.1.4.77 #define OBJ_ATTR_LONG( x, attrname, flags, val )

Create an instance-local long integer attribute and add it to a Max class.

Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
val Pointer to the value.

36.1.4.78 #define OBJ_ATTR_LONG_ARRAY( x, attrname, flags, count, vals )

Create an instance-local array-of-long-integers attribute of fixed length, and add it to the object.
Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
count The number of items in the long array.
vals Pointer to the values.

36.1.4.79 #define OBJ_ATTR_OBJ( x, attrname, flags, val )

Create an instance-local t_object∗ attribute and add it to a Max class.

Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
val Pointer to the value.

36.1.4.80 #define OBJ_ATTR_OBJ_ARRAY( x, attrname, flags, count, vals )

Create an instance-local array-of-objects attribute of fixed length, and add it to the object.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

176 Module Documentation

Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
count The number of items in the t_object∗ array.
vals Pointer to the values.

36.1.4.81 #define OBJ_ATTR_SAVE( x, attrname, flags )

An instance-attribute version of CLASS_ATTR_SAVE.

Parameters
x The t_object instance pointer.
attrname The name of the attribute as a C-string.
flags Any flags you wish to declare for this new attribute, as defined in e_max_attrflags.

See also

CLASS_ATTR_SAVE

36.1.4.82 #define OBJ_ATTR_SYM( x, attrname, flags, val )

Create an instance-local t_symbol∗ attribute and add it to a Max class.

Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
val Pointer to the value.

36.1.4.83 #define OBJ_ATTR_SYM_ARRAY( x, attrname, flags, count, vals )

Create an instance-local array-of-symbols attribute of fixed length, and add it to the object.
Parameters
x The object pointer.
attrname The name of this attribute as a C-string.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
count The number of items in the t_symbol∗ array.
vals Pointer to the values.

36.1.4.84 #define STRUCT_ATTR_ATOM( c, flags, structname, structmember )

Create a t_atom attribute and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 177

c The class pointer.

flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.85 #define STRUCT_ATTR_ATOM_ARRAY( c, flags, structname, structmember, size )

Create an array-of-atoms attribute of fixed length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of items in the t_atom array.

36.1.4.86 #define STRUCT_ATTR_ATOM_LONG( c, flags, structname, structmember )

Create a t_atom_long integer attribute and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.87 #define STRUCT_ATTR_ATOM_VARSIZE( c, flags, structname, structmember, sizemember, maxsize )

Create an array-of-atoms attribute of variable length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the t_atom array at any given moment.
maxsize The maximum number of items in the t_atom array, i.e. the number of members allocated for
the array in the struct.

36.1.4.88 #define STRUCT_ATTR_CHAR( c, flags, structname, structmember )

Create a char attribute and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

178 Module Documentation

Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.89 #define STRUCT_ATTR_CHAR_ARRAY( c, flags, structname, structmember, size )

Create an array-of-chars attribute of fixed length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of items in the char array.

36.1.4.90 #define STRUCT_ATTR_CHAR_VARSIZE( c, flags, structname, structmember, sizemember, maxsize )

Create an array-of-chars attribute of variable length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the char array at any given moment.
maxsize The maximum number of items in the char array, i.e. the number of members allocated for
the array in the struct.

36.1.4.91 #define STRUCT_ATTR_DOUBLE( c, flags, structname, structmember )

Create a 64bit float attribute and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.92 #define STRUCT_ATTR_DOUBLE_ARRAY( c, flags, structname, structmember, size )

Create an array-of-64bit-floats attribute of fixed length, and add it to a Max class.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 179

The name of the attribute is automatically determined by the name of the struct member.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

180 Module Documentation

Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of items in the double array.

36.1.4.93 #define STRUCT_ATTR_DOUBLE_VARSIZE( c, flags, structname, structmember, sizemember, maxsize )

Create an array-of-64bit-floats attribute of variable length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the double array at any given moment.
maxsize The maximum number of items in the double array, i.e. the number of members allocated for
the array in the struct.

36.1.4.94 #define STRUCT_ATTR_FLOAT( c, flags, structname, structmember )

Create a 32bit float attribute and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.95 #define STRUCT_ATTR_FLOAT_ARRAY( c, flags, structname, structmember, size )

Create an array-of-32bit-floats attribute of fixed length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 181

size The number of items in the floats array.

36.1.4.96 #define STRUCT_ATTR_FLOAT_VARSIZE( c, flags, structname, structmember, sizemember, maxsize )

Create an array-of-32bit-floats attribute of variable length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the float array at any given moment.
maxsize The maximum number of items in the float array, i.e. the number of members allocated for
the array in the struct.

36.1.4.97 #define STRUCT_ATTR_LONG( c, flags, structname, structmember )

Create a long integer attribute and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.98 #define STRUCT_ATTR_LONG_ARRAY( c, flags, structname, structmember, size )

Create an array-of-long-integers attribute of fixed length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of items in the long array.

36.1.4.99 #define STRUCT_ATTR_LONG_VARSIZE( c, flags, structname, structmember, sizemember, maxsize )

Create an array-of-long-integers attribute of variable length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

182 Module Documentation

Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the long array at any given moment.
maxsize The maximum number of items in the long array, i.e. the number of members allocated for
the array in the struct.

36.1.4.100 #define STRUCT_ATTR_OBJ( c, flags, structname, structmember )

Create a t_object∗ attribute and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.101 #define STRUCT_ATTR_OBJ_ARRAY( c, flags, structname, structmember, size )

Create an array-of-objects attribute of fixed length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of items in the t_object∗ array.

36.1.4.102 #define STRUCT_ATTR_OBJ_VARSIZE( c, flags, structname, structmember, sizemember, maxsize )

Create an array-of-objects attribute of variable length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 183

sizemember The actual number of items in the t_object∗ array at any given moment.
maxsize The maximum number of items in the t_object∗ array, i.e. the number of members allocated
for the array in the struct.

36.1.4.103 #define STRUCT_ATTR_SYM( c, flags, structname, structmember )

Create a t_symbol∗ attribute and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.

36.1.4.104 #define STRUCT_ATTR_SYM_ARRAY( c, flags, structname, structmember, size )

Create an array-of-symbols attribute of fixed length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
size The number of items in the t_symbol∗ array.

36.1.4.105 #define STRUCT_ATTR_SYM_VARSIZE( c, flags, structname, structmember, sizemember, maxsize )

Create an array-of-symbols attribute of variable length, and add it to a Max class.

The name of the attribute is automatically determined by the name of the struct member.
Parameters
c The class pointer.
flags Any flags you wish to declare for this attribute, as defined in e_max_attrflags.
structname The C identifier for the struct (containing a valid t_object header) representing an instance of
this class.
structmember The C identifier of the member in the struct that holds the value of this attribute.
sizemember The actual number of items in the t_symbol∗ array at any given moment.
maxsize The maximum number of items in the t_symbol∗ array, i.e. the number of members allocated
for the array in the struct.

36.1.5 Enumeration Type Documentation

36.1.5.1 enum e_max_attrflags

Attribute flags.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

 184 Module Documentation

Remarks

To create a readonly attribute, for example, you should pass ATTR_SET_OPAQUE or ATTR_SET_OPAQ←-
UE_USER as a flag when you create your attribute.

Enumerator

ATTR_FLAGS_NONE No flags.
ATTR_GET_OPAQUE The attribute cannot be queried by either max message when used inside of a CLA←-
SS_BOX object, nor from C code.
ATTR_SET_OPAQUE The attribute cannot be set by either max message when used inside of a CLASS_←-
BOX object, nor from C code.
ATTR_GET_OPAQUE_USER The attribute cannot be queried by max message when used inside of a CL←-
ASS_BOX object, but can be queried from C code.
ATTR_SET_OPAQUE_USER The attribute cannot be set by max message when used inside of a CLASS←-
_BOX object, but can be set from C code.

36.1.6 Function Documentation

36.1.6.1 t_max_err attr_addfilter_clip ( void ∗ x, double min, double max, long usemin, long usemax )

Attaches a clip filter to an attribute.

The filter will clip any values sent to or retrieved from the attribute using the attribute's get and set functions.
Parameters
x Pointer to the attribute to receive the filter
min Minimum value for the clip filter
max Maximum value for the clip filter
usemin Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.
usemax Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.2 t_max_err attr_addfilter_clip_scale ( void ∗ x, double scale, double min, double max, long usemin, long usemax )

Attaches a clip/scale filter to an attribute.

The filter will clip and scale any values sent to or retrieved from the attribute using the attribute's get and set
functions.
Parameters
x Pointer to the attribute to receive the filter
scale Scale value. Data sent to the attribute will be scaled by this amount. Data retrieved from the
attribute will be scaled by its reciprocal. Scaling occurs previous to clipping.
min Minimum value for the clip filter
max Maximum value for the clip filter
usemin Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.
usemax Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 185

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.3 t_max_err attr_addfilterget_clip ( void ∗ x, double min, double max, long usemin, long usemax )

Attaches a clip filter to an attribute.

The filter will only clip values retrieved from the attribute using the attribute's get function.
Parameters
x Pointer to the attribute to receive the filter
min Minimum value for the clip filter
max Maximum value for the clip filter
usemin Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.
usemax Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.4 t_max_err attr_addfilterget_clip_scale ( void ∗ x, double scale, double min, double max, long usemin, long
usemax )

Attaches a clip/scale filter to an attribute.

The filter will only clip and scale values retrieved from the attribute using the attribute's get function.
Parameters
x Pointer to the attribute to receive the filter
scale Scale value. Data retrieved from the attribute will be scaled by this amount. Scaling occurs
previous to clipping.
min Minimum value for the clip filter
max Maximum value for the clip filter
usemin Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.
usemax Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.5 t_max_err attr_addfilterget_proc ( void ∗ x, method proc )

Attaches a custom filter method to an attribute.

The filter will only be called for values retrieved from the attribute using the attribute's get function.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

186 Module Documentation

Parameters
x Pointer to the attribute to receive the filter
proc A filter method

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Remarks

The filter method should be prototyped and implemented as described above for the attr_addfilterset_proc()
function.

36.1.6.6 t_max_err attr_addfilterset_clip ( void ∗ x, double min, double max, long usemin, long usemax )

Attaches a clip filter to an attribute.

The filter will only clip values sent to the attribute using the attribute's set function.
Parameters
x Pointer to the attribute to receive the filter
min Minimum value for the clip filter
max Maximum value for the clip filter
usemin Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.
usemax Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.7 t_max_err attr_addfilterset_clip_scale ( void ∗ x, double scale, double min, double max, long usemin, long usemax
)

Attaches a clip/scale filter to an attribute.

The filter will only clip and scale values sent to the attribute using the attribute's set function.
Parameters
x Pointer to the attribute to receive the filter
scale Scale value. Data sent to the attribute will be scaled by this amount. Scaling occurs previous
to clipping.
min Minimum value for the clip filter
max Maximum value for the clip filter
usemin Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.
usemax Sets this value to 0 if the minimum clip value should not be used. Otherwise, set the value to
non-zero.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 187

36.1.6.8 t_max_err attr_addfilterset_proc ( void ∗ x, method proc )

Attaches a custom filter method to an attribute.

The filter will only be called for values retrieved from the attribute using the attribute's set function.
Parameters
x Pointer to the attribute to receive the filter
proc A filter method

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Remarks

The filter method should be prototyped and implemented as follows:

1 t_max_err myfiltermethod(void *parent, void *attr, long ac, t_atom *av);

2
3 t_max_err myfiltermethod(void *parent, void *attr, long ac, t_atom *av)
4 {
5 long i;
6 float temp,
7
8 // this filter rounds off all values
9 // assumes that the data is float
10 for (i = 0; i < ac; i++) {
11 temp = atom_getfloat(av + i);
12 temp = (float)((long)(temp + 0.5));
13 atom_setfloat(av + i, temp);
14 }
15 return MAX_ERR_NONE;
16 }

36.1.6.9 void attr_args_dictionary ( t_dictionary ∗ x, short ac, t_atom ∗ av )

Create a dictionary of attribute-name, attribute-value pairs from an array of atoms containing an attribute definition
list.
Parameters
x A dictionary instance pointer.
ac The number of atoms to parse in av.
av A pointer to the first of the array of atoms containing the attribute values.

Remarks

The code example below shows the creation of a list of atoms using atom_setparse(), and then uses that list
of atoms to fill the dictionary with attr_args_dictionary().

1 long ac = 0;
2 t_atom *av = NULL;
3 char parsebuf[4096];
4 t_dictionary *d = dictionary_new();
5 t_atom a;
6
7 sprintf(parsebuf,"@defrect %.6f %.6f %.6f %.6f @title Untitled @presentation 0 ", r->x, r->y, r->width,
r->height);
8 atom_setparse(&ac, &av, parsebuf);
9 attr_args_dictionary(d, ac, av);
10 atom_setobj(&a, d);

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

188 Module Documentation

36.1.6.10 long attr_args_offset ( short ac, t_atom ∗ av )

Determines the point in an atom list where attribute arguments begin.

Developers can use this function to assist in the manual processing of attribute arguments, when attr_args_←-
process() doesn't provide the correct functionality for a particular purpose.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 189

Parameters
ac The count of t_atoms in av
av An atom list

Returns

This function returns an offset into the atom list, where the first attribute argument occurs. For instance, the
atom list foo bar 3.0 @mode 6 would cause attr_args_offset to return 3 (the attribute mode
appears at position 3 in the atom list).

Referenced by max_jit_attr_args_offset().

36.1.6.11 void attr_args_process ( void ∗ x, short ac, t_atom ∗ av )

Takes an atom list and properly set any attributes described within.
This function is typically used in an object's new method to conveniently process attribute arguments.
Parameters
x The object whose attributes will be processed
ac The count of t_atoms in av
av An atom list

Remarks

Here is a typical example of usage:

1 void *myobject_new(t_symbol *s, long ac, t_atom *av)

2 {
3 t_myobject *x = NULL;
4
5 if (x=(t_myobject *)object_alloc(myobject_class))
6 {
7 // initialize any data before processing
8 // attributes to avoid overwriting
9 // attribute argument-set values
10 x->data = 0;
11
12 // process attr args, if any
13 attr_args_process(x, ac, av);
14 }
15 return x;
16 }

36.1.6.12 void attr_dictionary_check ( void ∗ x, t_dictionary ∗ d )

Check that a dictionary only contains values for existing attributes of an object.
If a key in the dictionary doesn't correspond an one of the object's attributes, an error will be posted to the Max
window.
Parameters
x The object instance pointer.
d The dictionary containing the attributes.

See also

attr_dictionary_process()

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

190 Module Documentation

36.1.6.13 void attr_dictionary_process ( void ∗ x, t_dictionary ∗ d )

Set attributes for an object that are defined in a dictionary.

Objects with dictionary constructors, such as UI objects, should call this method to set their attributes when an
object is created.
Parameters
x The object instance pointer.
d The dictionary containing the attributes.

See also

attr_args_process()

36.1.6.14 t_object∗ attr_offset_array_new ( C74_CONST char ∗ name, t_symbol ∗ type, long size, long flags, method
mget, method mset, long offsetcount, long offset )

Create a new attribute.

The attribute references an array of memory stored outside of itself, in the object's data structure. Attributes created
using attr_offset_array_new() can be assigned either to classes (using the class_addattr() function) or to objects
(using the object_addattr() function).
Parameters
name A name for the attribute, as a C-string
type A t_symbol ∗ representing a valid attribute type. At the time of this writing, the valid type-
symbols are: _sym_char (char), _sym_long (long), _sym_float32 (32-bit float), ←-
_sym_float64 (64-bit float), _sym_atom (Max t_atom pointer), _sym_symbol (Max
t_symbol pointer), _sym_pointer (generic pointer) and _sym_object (Max t_object
pointer).
size Maximum number of items that may be in the array.
flags Any attribute flags, expressed as a bitfield. Attribute flags are used to determine if an attribute
is accessible for setting or querying. The available accessor flags are defined in e_max_←-
attrflags.
mget The method to use for the attribute's get functionality. If mget is NULL, the default method
is used. See the discussion under attribute_new(), for more information.
mset The method to use for the attribute's set functionality. If mset is NULL, the default method
is used. See the discussion under attribute_new(), for more information.
offsetcount Byte offset into the object class's data structure of a long variable describing how many array
elements (up to size) comprise the data to be referenced by the attribute. Typically, the
calcoffset macro is used to calculate this offset.
offset Byte offset into the class data structure of the object which will "own" the attribute. The offset
should point to the data to be referenced by the attribute. Typically, the calcoffset macro is
used to calculate this offset.

Returns

This function returns the new attribute's object pointer if successful, or NULL if unsuccessful.

Remarks

For instance, to create a new attribute which references an array of 10 t_atoms (atm; the current number of
"active" elements in the array is held in the variable atmcount) in an object class's data structure:
1 t_object *attr = attr_offset_array_new("myattrarray", _sym_atom / * matches data size * /, 10 / * max * /,
0 / * no flags * /, (method)0L, (method)0L, calcoffset(t_myobject, atmcount) / * count * /,
calcoffset(t_myobject, atm) / * data * /);

Referenced by ext_main().

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 191

36.1.6.15 t_object∗ attr_offset_new ( C74_CONST char ∗ name, C74_CONST t_symbol ∗ type, long flags, C74_CONST
method mget, C74_CONST method mset, long offset )

Create a new attribute.

The attribute references memory stored outside of itself, in the object's data structure. Attributes created using
attr_offset_new() can be assigned either to classes (using the class_addattr() function) or to objects (using the
object_addattr() function).
Parameters
name A name for the attribute, as a C-string
type A t_symbol ∗ representing a valid attribute type. At the time of this writing, the valid type-
symbols are: _sym_char (char), _sym_long (long), _sym_float32 (32-bit float), ←-
_sym_float64 (64-bit float), _sym_atom (Max t_atom pointer), _sym_symbol (Max
t_symbol pointer), _sym_pointer (generic pointer) and _sym_object (Max t_object
pointer).
flags Any attribute flags, expressed as a bitfield. Attribute flags are used to determine if an attribute
is accessible for setting or querying. The available accessor flags are defined in e_max_←-
attrflags.
mget The method to use for the attribute's get functionality. If mget is NULL, the default method
is used. See the discussion under attribute_new(), for more information.
mset The method to use for the attribute's set functionality. If mset is NULL, the default method
is used. See the discussion under attribute_new(), for more information.
offset Byte offset into the class data structure of the object which will "own" the attribute. The offset
should point to the data to be referenced by the attribute. Typically, the calcoffset macro
(described above) is used to calculate this offset.

Returns

This function returns the new attribute's object pointer if successful, or NULL if unsuccessful.

Remarks

For instance, to create a new attribute which references the value of a double variable (val) in an object
class's data structure:

1 t_object *attr = attr_offset_new("myattr", _sym_float64 / * matches data size * /, 0 / * no flags * /,

(method)0L, (method)0L, calcoffset(t_myobject, val));

Referenced by ext_main().

36.1.6.16 t_object∗ attribute_new ( C74_CONST char ∗ name, t_symbol ∗ type, long flags, method mget, method mset
)

Create a new attribute.

The attribute will allocate memory and store its own data. Attributes created using attribute_new() can be assigned
either to classes (using the class_addattr() function) or to objects (using the object_addattr() function).

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

192 Module Documentation

Parameters
name A name for the attribute, as a C-string
type A t_symbol ∗ representing a valid attribute type. At the time of this writing, the valid type-
symbols are: _sym_char (char), _sym_long (long), _sym_float32 (32-bit float), ←-
_sym_float64 (64-bit float), _sym_atom (Max t_atom pointer), _sym_symbol (Max
t_symbol pointer), _sym_pointer (generic pointer) and _sym_object (Max t_object
pointer).
flags Any attribute flags, expressed as a bitfield. Attribute flags are used to determine if an attribute
is accessible for setting or querying. The available accessor flags are defined in e_max_←-
attrflags.
mget The method to use for the attribute's get functionality. If mget is NULL, the default method
is used.
mset The method to use for the attribute's set functionality. If mset is NULL, the default method
is used.

Returns

This function returns the new attribute's object pointer if successful, or NULL if unsuccessful.

Remarks

Developers wishing to define custom methods for get or set functionality need to prototype them as:

1 t_max_err myobject_myattr_get(t_myobject *x, void *attr, long *ac, t_atom **av);

1 t_max_err myobject_myattr_set(t_myobject *x, void *attr, long ac, t_atom *av);

Implementation will vary, of course, but need to follow the following basic models. Note that, as with cus-
tom getvalueof and setvalueof methods for the object, assumptions are made throughout Max that
getbytes() has been used for memory allocation. Developers are strongly urged to do the same:

1 t_max_err myobject_myattr_get(t_myobject *x, void *attr, long *ac, t_atom **av)

2 {
3 if (*ac && *av)
4 // memory passed in; use it
5 else {
6 *ac = 1; // size of attr data
7 *av = (t_atom *)getbytes(sizeof(t_atom) * (*ac));
8 if (!(*av)) {
9 *ac = 0;
10 return MAX_ERR_OUT_OF_MEM;
11 }
12 }
13 atom_setlong(*av, x->some_value);
14 return MAX_ERR_NONE;
15 }
16
17 t_max_err myobject_myattr_set(t_myobject *x, void *attr, long ac, t_atom *av)
18 {
19 if (ac && av) {
20 x->some_value = atom_getlong(av);
21 }
22 return MAX_ERR_NONE;
23 }

36.1.6.17 t_max_err object_addattr ( void ∗ x, t_object ∗ attr )

Attaches an attribute directly to an object.

Parameters

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 193

x An object to which the attribute should be attached

attr The attribute's pointer—this should be a pointer returned from attribute_new(), attr_offset_←-
new() or attr_offset_array_new().

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.18 void∗ object_attr_get ( void ∗ x, t_symbol ∗ attrname )

Returns the pointer to an attribute, given its name.

Parameters
x Pointer to the object whose attribute is of interest
attrname The attribute's name

Returns

This function returns a pointer to the attribute, if successful, or NULL, if unsuccessful.

Referenced by jit_attr_getchar_array(), jit_attr_getdouble_array(), jit_attr_getfloat(), jit_attr_getfloat_array(), jit_←-

attr_getlong(), jit_attr_getlong_array(), jit_attr_getsym(), jit_attr_getsym_array(), jit_attr_setchar_array(), jit_attr←-
_setdouble_array(), jit_attr_setfloat(), jit_attr_setfloat_array(), jit_attr_setlong(), jit_attr_setlong_array(), jit_attr_←-
setsym(), jit_attr_setsym_array(), jit_object_attr_get(), jit_object_exportattrs(), and max_jit_attr_set().

36.1.6.19 t_max_err object_attr_get_rect ( t_object ∗ o, t_symbol ∗ name, t_rect ∗ rect )

Gets the value of a t_rect attribute, given its parent object and name.
Do not use this on a jbox object – use jbox_get_rect_for_view() instead!
Parameters
o The attribute's parent object
name The attribute's name
rect The address of a valid t_rect whose values will be filled-in from the attribute.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.20 long object_attr_getchar_array ( void ∗ x, t_symbol ∗ s, long max, t_uint8 ∗ vals )

Retrieves the value of an attribute, given its parent object and name.
This function uses a developer-allocated array to copy data to. Developers wishing to retrieve the value of an
attribute without pre-allocating memory should refer to the object_attr_getvalueof() function.
Parameters
x The attribute's parent object
s The attribute's name
max The number of array elements in vals. The function will take care not to overwrite the
bounds of the array.
vals Pointer to the first element of a pre-allocated array of unsigned char data.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

194 Module Documentation

Returns

This function returns the number of elements copied into vals.

Remarks

If the attribute is not of the type specified by the function, the function will attempt to coerce a valid value from
the attribute.

Referenced by jit_attr_getchar_array().

36.1.6.21 t_max_err object_attr_getcolor ( t_object ∗ b, t_symbol ∗ attrname, t_jrgba ∗ prgba )

Gets the value of a t_jrgba attribute, given its parent object and name.
Parameters
b The attribute's parent object
attrname The attribute's name
prgba The address of a valid t_jrgba whose values will be filled-in from the attribute.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.22 long object_attr_getdouble_array ( void ∗ x, t_symbol ∗ s, long max, double ∗ vals )

Retrieves the value of an attribute, given its parent object and name.
This function uses a developer-allocated array to copy data to. Developers wishing to retrieve the value of an
attribute without pre-allocating memory should refer to the object_attr_getvalueof() function.
Parameters
x The attribute's parent object
s The attribute's name
max The number of array elements in vals. The function will take care not to overwrite the
bounds of the array.
vals Pointer to the first element of a pre-allocated array of double data.

Returns

This function returns the number of elements copied into vals.

Remarks

If the attribute is not of the type specified by the function, the function will attempt to coerce a valid value from
the attribute.

Referenced by jit_attr_getdouble_array().

36.1.6.23 void object_attr_getdump ( void ∗ x, t_symbol ∗ s, long argc, t_atom ∗ argv )

Forces a specified object's attribute to send its value from the object's dumpout outlet in the Max interface.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 195

Parameters
x Pointer to the object whose attribute is of interest
s The attribute's name
argc Unused
argv Unused

36.1.6.24 t_atom_float object_attr_getfloat ( void ∗ x, t_symbol ∗ s )

Retrieves the value of an attribute, given its parent object and name.
Parameters
x The attribute's parent object
s The attribute's name

Returns

This function returns the value of the specified attribute, if successful, or 0, if unsuccessful.

Remarks

If the attribute is not of the type specified by the function, the function will attempt to coerce a valid value from
the attribute.

Referenced by jit_attr_getfloat().

36.1.6.25 long object_attr_getfloat_array ( void ∗ x, t_symbol ∗ s, long max, float ∗ vals )

Retrieves the value of an attribute, given its parent object and name.
This function uses a developer-allocated array to copy data to. Developers wishing to retrieve the value of an
attribute without pre-allocating memory should refer to the object_attr_getvalueof() function.
Parameters
x The attribute's parent object
s The attribute's name
max The number of array elements in vals. The function will take care not to overwrite the
bounds of the array.
vals Pointer to the first element of a pre-allocated array of float data.

Returns

This function returns the number of elements copied into vals.

Remarks

If the attribute is not of the type specified by the function, the function will attempt to coerce a valid value from
the attribute.

Referenced by jit_attr_getfloat_array().

36.1.6.26 t_max_err object_attr_getjrgba ( void ∗ ob, t_symbol ∗ s, t_jrgba ∗ c )

Retrieves the value of a color attribute, given its parent object and name.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

196 Module Documentation

Parameters
ob The attribute's parent object
s The attribute's name
c The address of a t_jrgba struct that will be filled with the attribute's color component values.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.27 t_atom_long object_attr_getlong ( void ∗ x, t_symbol ∗ s )

Retrieves the value of an attribute, given its parent object and name.
Parameters
x The attribute's parent object
s The attribute's name

Returns

This function returns the value of the specified attribute, if successful, or 0, if unsuccessful.

Remarks

If the attribute is not of the type specified by the function, the function will attempt to coerce a valid value from
the attribute.

Referenced by jit_attr_getlong().

36.1.6.28 long object_attr_getlong_array ( void ∗ x, t_symbol ∗ s, long max, t_atom_long ∗ vals )

Retrieves the value of an attribute, given its parent object and name.
This function uses a developer-allocated array to copy data to. Developers wishing to retrieve the value of an
attribute without pre-allocating memory should refer to the object_attr_getvalueof() function.
Parameters
x The attribute's parent object
s The attribute's name
max The number of array elements in vals. The function will take care not to overwrite the
bounds of the array.
vals Pointer to the first element of a pre-allocated array of long data.

Returns

This function returns the number of elements copied into vals.

Remarks

If the attribute is not of the type specified by the function, the function will attempt to coerce a valid value from
the attribute.

Referenced by jit_attr_getlong_array().

36.1.6.29 t_max_err object_attr_getpt ( t_object ∗ o, t_symbol ∗ name, t_pt ∗ pt )

Gets the value of a t_pt attribute, given its parent object and name.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 197

Parameters
o The attribute's parent object
name The attribute's name
pt The address of a valid t_pt whose values will be filled-in from the attribute.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.30 t_max_err object_attr_getsize ( t_object ∗ o, t_symbol ∗ name, t_size ∗ size )

Gets the value of a t_size attribute, given its parent object and name.
Parameters
o The attribute's parent object
name The attribute's name
size The address of a valid t_size whose values will be filled-in from the attribute.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.31 t_symbol∗ object_attr_getsym ( void ∗ x, t_symbol ∗ s )

Retrieves the value of an attribute, given its parent object and name.
Parameters
x The attribute's parent object
s The attribute's name

Returns

This function returns the value of the specified attribute, if successful, or the empty symbol (equivalent to
gensym("") or _sym_nothing), if unsuccessful.

Referenced by jit_attr_getsym().

36.1.6.32 long object_attr_getsym_array ( void ∗ x, t_symbol ∗ s, long max, t_symbol ∗∗ vals )

Retrieves the value of an attribute, given its parent object and name.
This function uses a developer-allocated array to copy data to. Developers wishing to retrieve the value of an
attribute without pre-allocating memory should refer to the object_attr_getvalueof() function.
Parameters
x The attribute's parent object
s The attribute's name
max The number of array elements in vals. The function will take care not to overwrite the
bounds of the array.
vals Pointer to the first element of a pre-allocated array of t_symbol ∗s.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

198 Module Documentation

Returns

This function returns the number of elements copied into vals.

Referenced by jit_attr_getsym_array().

36.1.6.33 method object_attr_method ( void ∗ x, t_symbol ∗ methodname, void ∗∗ attr, long ∗ get )

Returns the method of an attribute's get or set function, as well as a pointer to the attribute itself, from a message
name.
Parameters
x Pointer to the object whose attribute is of interest
methodname The Max message used to call the attribute's get or set function. For example,
gensym("mode") or gensym("getthresh").
attr A pointer to a void ∗, which will be set to the attribute pointer upon successful completion of
the function
get A pointer to a long variable, which will be set to 1 upon successful completion of the function,
if the queried method corresponds to the get function of the attribute.

Returns

This function returns the requested method, if successful, or NULL, if unsuccessful.

36.1.6.34 t_max_err object_attr_set_rect ( t_object ∗ o, t_symbol ∗ name, t_rect ∗ rect )

Sets the value of a t_rect attribute, given its parent object and name.
Do not use this on a jbox object – use jbox_get_rect_for_view() instead!
Parameters
o The attribute's parent object
name The attribute's name
rect The address of a valid t_rect whose values will be used to set the attribute.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.35 void object_attr_set_xywh ( t_object ∗ o, t_symbol ∗ attr, double x, double y, double w, double h )

Sets the value of a t_rect attribute, given its parent object and name.
Do not use this on a jbox object – use jbox_get_rect_for_view() instead!
Parameters
o The attribute's parent object
attr The attribute's name
x A double containing the new x position.
y A double containing the new y position.
w A double containing the new width.
h A double containing the new height.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 199

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.36 t_max_err object_attr_setchar_array ( void ∗ x, t_symbol ∗ s, long count, C74_CONST t_uint8 ∗ vals )

Sets the value of an attribute, given its parent object and name.
The function will call the attribute's set method, using the data provided.
Parameters
x The attribute's parent object
s The attribute's name
count The number of array elements in vals
vals Pointer to the first element of an array of unsigned char data

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by jit_attr_setchar_array().

36.1.6.37 t_max_err object_attr_setcolor ( t_object ∗ b, t_symbol ∗ attrname, t_jrgba ∗ prgba )

Sets the value of a t_jrgba attribute, given its parent object and name.
Parameters
b The attribute's parent object
attrname The attribute's name
prgba The address of a valid t_jrgba whose values will be used to set the attribute.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.38 t_max_err object_attr_setdouble_array ( void ∗ x, t_symbol ∗ s, long count, double ∗ vals )

Sets the value of an attribute, given its parent object and name.
The function will call the attribute's set method, using the data provided.
Parameters
x The attribute's parent object
s The attribute's name
count The number of array elements in vals
vals Pointer to the first element of an array of double data

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by jit_attr_setdouble_array().

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

200 Module Documentation

36.1.6.39 t_max_err object_attr_setfloat ( void ∗ x, t_symbol ∗ s, t_atom_float c )

Sets the value of an attribute, given its parent object and name.
The function will call the attribute's set method, using the data provided.
Parameters
x The attribute's parent object
s The attribute's name
c An floating point value; the new value for the attribute

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by jit_attr_setfloat().

36.1.6.40 t_max_err object_attr_setfloat_array ( void ∗ x, t_symbol ∗ s, long count, float ∗ vals )

Sets the value of an attribute, given its parent object and name.
The function will call the attribute's set method, using the data provided.
Parameters
x The attribute's parent object
s The attribute's name
count The number of array elements in vals
vals Pointer to the first element of an array of float data

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by jit_attr_setfloat_array().

36.1.6.41 t_max_err object_attr_setjrgba ( void ∗ ob, t_symbol ∗ s, t_jrgba ∗ c )

Sets the value of a color attribute, given its parent object and name.
The function will call the attribute's set method, using the data provided.
Parameters
ob The attribute's parent object
s The attribute's name
c The address of a t_jrgba struct that contains the new color.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.42 t_max_err object_attr_setlong ( void ∗ x, t_symbol ∗ s, t_atom_long c )

Sets the value of an attribute, given its parent object and name.
The function will call the attribute's set method, using the data provided.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 201

Parameters
x The attribute's parent object
s The attribute's name
c An integer value; the new value for the attribute

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by jit_attr_setlong().

36.1.6.43 t_max_err object_attr_setlong_array ( void ∗ x, t_symbol ∗ s, long count, t_atom_long ∗ vals )

Sets the value of an attribute, given its parent object and name.
The function will call the attribute's set method, using the data provided.
Parameters
x The attribute's parent object
s The attribute's name
count The number of array elements in vals
vals Pointer to the first element of an array of long data

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by jit_attr_setlong_array().

36.1.6.44 t_max_err object_attr_setparse ( t_object ∗ x, t_symbol ∗ s, C74_CONST char ∗ parsestr )

Set an attribute value with one or more atoms parsed from a C-string.
Parameters
x The object whose attribute will be set.
s The name of the attribute to set.
parsestr A C-string to parse into an array of atoms to set the attribute value.

Returns

A Max error code.

See also

atom_setparse()

36.1.6.45 t_max_err object_attr_setpt ( t_object ∗ o, t_symbol ∗ name, t_pt ∗ pt )

Sets the value of a t_pt attribute, given its parent object and name.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

202 Module Documentation

Parameters
o The attribute's parent object
name The attribute's name
pt The address of a valid t_pt whose values will be used to set the attribute.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.46 t_max_err object_attr_setsize ( t_object ∗ o, t_symbol ∗ name, t_size ∗ size )

Sets the value of a t_size attribute, given its parent object and name.
Parameters
o The attribute's parent object
name The attribute's name
size The address of a valid t_size whose values will be used to set the attribute.

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.47 t_max_err object_attr_setsym ( void ∗ x, t_symbol ∗ s, t_symbol ∗ c )

Sets the value of an attribute, given its parent object and name.
The function will call the attribute's set method, using the data provided.
Parameters
x The attribute's parent object
s The attribute's name
c A t_symbol ∗; the new value for the attribute

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by jit_attr_setsym().

36.1.6.48 t_max_err object_attr_setsym_array ( void ∗ x, t_symbol ∗ s, long count, t_symbol ∗∗ vals )

Sets the value of an attribute, given its parent object and name.
The function will call the attribute's set method, using the data provided.
Parameters
x The attribute's parent object

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.1 Attributes 203

s The attribute's name

count The number of array elements in vals
vals Pointer to the first element of an array of t_symbol ∗s

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by jit_attr_setsym_array().

36.1.6.49 t_max_err object_attr_setvalueof ( void ∗ x, t_symbol ∗ s, long argc, t_atom ∗ argv )

Sets the value of an object's attribute.

Parameters
x Pointer to the object whose attribute is of interest
s The attribute's name
argc The count of arguments in argv
argv Array of t_atoms; the new desired data for the attribute

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by jit_object_importattrs().

36.1.6.50 long object_attr_usercanget ( void ∗ x, t_symbol ∗ s )

Determines if the value of an object's attribute can be queried from the Max interface (i.e.
if its ATTR_GET_OPAQUE_USER flag is set).
Parameters
x Pointer to the object whose attribute is of interest
s The attribute's name

Returns

This function returns 1 if the value of the attribute can be queried from the Max interface. Otherwise, it returns
0.

Referenced by jit_object_attr_usercanget().

36.1.6.51 long object_attr_usercanset ( void ∗ x, t_symbol ∗ s )

Determines if an object's attribute can be set from the Max interface (i.e.
if its ATTR_SET_OPAQUE_USER flag is set).
Parameters
x Pointer to the object whose attribute is of interest
s The attribute's name

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

204 Module Documentation

Returns

This function returns 1 if the attribute can be set from the Max interface. Otherwise, it returns 0.

Referenced by jit_object_attr_usercanset().

36.1.6.52 t_max_err object_chuckattr ( void ∗ x, t_symbol ∗ attrsym )

Detach an attribute from an object that was previously attached with object_addattr().
This function will not free the attribute (use object_free() to do this manually).
Parameters
x The object to which the attribute is attached
attrsym The attribute's name

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.53 t_max_err object_deleteattr ( void ∗ x, t_symbol ∗ attrsym )

Detach an attribute from an object that was previously attached with object_addattr().
The function will also free all memory associated with the attribute. If you only wish to detach the attribute, without
freeing it, see the object_chuckattr() function.
Parameters
x The object to which the attribute is attached
attrsym The attribute's name

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.1.6.54 void∗ object_new_parse ( t_symbol ∗ name_space, t_symbol ∗ classname, C74_CONST char ∗ parsestr )

Create a new object with one or more atoms parsed from a C-string.
The object's new method must have an A_GIMME signature.
Parameters
name_space The namespace in which to create the instance. Typically this is either CLASS_BOX or CL←-
ASS_NOBOX.
classname The name of the class to instantiate.
parsestr A C-string to parse into an array of atoms to set the attribute value.

Returns

A pointer to the new instance.

See also

atom_setparse()
object_new_typed()

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.2 Classes 205

36.2 Classes

When a user types the name of your object into an object box, Max looks for an external of this name in the
searchpath and, upon finding it, loads the bundle or dll and calls the ext_main() function.
Collaboration diagram for Classes:

Inlets and Outlets

Classes
Old-Style Classes

Modules

• Old-Style Classes
• Inlets and Outlets
Routines for creating and communicating with inlets and outlets.

Data Structures

• struct t_class
The data structure for a Max class.

Macros

• #define CLASS_BOX
The namespace for all Max object classes which can be instantiated in a box, i.e.
• #define CLASS_NOBOX
A namespace for creating hidden or internal object classes which are not a direct part of the user creating patcher.

Enumerations

• enum e_max_class_flags {
CLASS_FLAG_BOX, CLASS_FLAG_POLYGLOT, CLASS_FLAG_NEWDICTIONARY, CLASS_FLAG_R←-
EGISTERED,
CLASS_FLAG_UIOBJECT, CLASS_FLAG_ALIAS, CLASS_FLAG_DO_NOT_PARSE_ATTR_ARGS, CL←-
ASS_FLAG_DO_NOT_ZERO,
CLASS_FLAG_NOATTRIBUTES, CLASS_FLAG_OWNATTRIBUTES, CLASS_FLAG_PARAMETER, CL←-
ASS_FLAG_RETYPEABLE,
CLASS_FLAG_OBJECT_METHOD }
Class flags.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

206 Module Documentation

Functions

• BEGIN_USING_C_LINKAGE void C74_EXPORT ext_main (void ∗r)

ext_main() is the entry point for an extern to be loaded, which all externs must implement this shared/common
prototype ensures that it will be exported correctly on all platforms.
• t_class ∗ class_new (C74_CONST char ∗name, C74_CONST method mnew, C74_CONST method mfree,
long size, C74_CONST method mmenu, short type,...)
Initializes a class by informing Max of its name, instance creation and free functions, size and argument types.
• t_max_err class_free (t_class ∗c)
Frees a previously defined object class.
• t_max_err class_register (t_symbol ∗name_space, t_class ∗c)
Registers a previously defined object class.
• t_max_err class_alias (t_class ∗c, t_symbol ∗aliasname)
Registers an alias for a previously defined object class.
• t_max_err class_addmethod (t_class ∗c, C74_CONST method m, C74_CONST char ∗name,...)
Adds a method to a previously defined object class.
• t_max_err class_addattr (t_class ∗c, t_object ∗attr)
Adds an attribute to a previously defined object class.
• t_symbol ∗ class_nameget (t_class ∗c)
Retrieves the name of a class, given the class's pointer.
• t_class ∗ class_findbyname (t_symbol ∗name_space, t_symbol ∗classname)
Finds the class pointer for a class, given the class's namespace and name.
• t_class ∗ class_findbyname_casefree (t_symbol ∗name_space, t_symbol ∗classname)
Finds the class pointer for a class, given the class's namespace and name.
• t_max_err class_dumpout_wrap (t_class ∗c)
Wraps user gettable attributes with a method that gets the values and sends out dumpout outlet.
• void class_obexoffset_set (t_class ∗c, long offset)
Registers the byte-offset of the obex member of the class's data structure with the previously defined object class.
• long class_obexoffset_get (t_class ∗c)
Retrieves the byte-offset of the obex member of the class's data structure.
• long class_is_ui (t_class ∗c)
Determine if a class is a user interface object.
• t_max_err class_subclass (t_class ∗superclass, t_class ∗subclass)
Define a subclass of an existing class.
• t_object ∗ class_super_construct (t_class ∗c,...)
Call super class constructor.

36.2.1 Detailed Description

When a user types the name of your object into an object box, Max looks for an external of this name in the
searchpath and, upon finding it, loads the bundle or dll and calls the ext_main() function.
Thus, Max classes are typically defined in the ext_main() function of an external.
Historically, Max classes have been defined using an API that includes functions like setup() and addmess(). This
interface is still supported, and the relevant documentation can be found in Old-Style Classes.
A more recent and more flexible interface for creating objects was introduced with Jitter 1.0 and later included
directly in Max 4.5. This newer API includes functions such as class_new() and class_addmethod(). Supporting
attributes, user interface objects, and additional new features of Max requires the use of the newer interface for
definiting classes documented on this page.
You may not mix these two styles of creating classes within an object.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

 36.2 Classes 207

36.2.2 Macro Definition Documentation

36.2.2.1 #define CLASS_BOX

The namespace for all Max object classes which can be instantiated in a box, i.e.
in a patcher.
Referenced by ext_main().

36.2.3 Enumeration Type Documentation

36.2.3.1 enum e_max_class_flags

Class flags.
If not box or polyglot, class is only accessible in C via known interface

Enumerator

CLASS_FLAG_BOX for use in a patcher

CLASS_FLAG_POLYGLOT for use by any text language (c/js/java/etc)
CLASS_FLAG_NEWDICTIONARY dictionary based constructor
CLASS_FLAG_REGISTERED for backward compatible messlist implementation (once reg'd can't grow)
CLASS_FLAG_UIOBJECT for objects that don't go inside a newobj box.
CLASS_FLAG_ALIAS for classes that are just copies of some other class (i.e. del is a copy of delay)
CLASS_FLAG_DO_NOT_PARSE_ATTR_ARGS override dictionary based constructor attr arg parsing
CLASS_FLAG_DO_NOT_ZERO don't zero the object struct on construction (for efficiency)
CLASS_FLAG_NOATTRIBUTES for efficiency
CLASS_FLAG_OWNATTRIBUTES for classes which support a custom attr interface (e.g. jitter)
CLASS_FLAG_PARAMETER for classes which have a parameter
CLASS_FLAG_RETYPEABLE object box can be retyped without recreating the object
CLASS_FLAG_OBJECT_METHOD objects of this class may have object specific methods

36.2.4 Function Documentation

36.2.4.1 t_max_err class_addattr ( t_class ∗ c, t_object ∗ attr )

Adds an attribute to a previously defined object class.

Parameters
c The class pointer
attr The attribute to add. The attribute will be a pointer returned by attribute_new(), attr_offset←-
_new() or attr_offset_array_new().

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by ext_main(), and jit_class_addattr().

36.2.4.2 t_max_err class_addmethod ( t_class ∗ c, C74_CONST method m, C74_CONST char ∗ name, ... )

Adds a method to a previously defined object class.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

208 Module Documentation

Parameters
c The class pointer
m Function to be called when the method is invoked
name C-string defining the message (message selector)
... One or more integers specifying the arguments to the message, in the standard Max type list
format (see Chapter 3 of the Writing Externals in Max document for more information).

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Remarks

The class_addmethod() function works essentially like the traditional addmess() function, adding the function
pointed to by m, to respond to the message string name in the leftmost inlet of the object.

Referenced by ext_main(), jit_class_addmethod(), jit_class_new(), and max_jit_class_ob3d_wrap().

36.2.4.3 t_max_err class_alias ( t_class ∗ c, t_symbol ∗ aliasname )

Registers an alias for a previously defined object class.

Parameters
c The class pointer
aliasname A symbol who's name will become an alias for the given class

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.2.4.4 t_max_err class_dumpout_wrap ( t_class ∗ c )

Wraps user gettable attributes with a method that gets the values and sends out dumpout outlet.
Parameters
c The class pointer

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

36.2.4.5 t_class∗ class_findbyname ( t_symbol ∗ name_space, t_symbol ∗ classname )

Finds the class pointer for a class, given the class's namespace and name.
Parameters

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.2 Classes 209

name_space The desired class's name space. Typically, either the constant CLASS_BOX, for obex classes
which can instantiate inside of a Max patcher (e.g. boxes, UI objects, etc.), or the constant
CLASS_NOBOX, for classes which will only be used internally. Developers can define their
own name spaces as well, but this functionality is currently undocumented.
classname The name of the class to be looked up

Returns

If successful, this function returns the class's data pointer. Otherwise, it returns NULL.

Referenced by jit_class_findbyname().

36.2.4.6 t_class∗ class_findbyname_casefree ( t_symbol ∗ name_space, t_symbol ∗ classname )

Finds the class pointer for a class, given the class's namespace and name.
Parameters
name_space The desired class's name space. Typically, either the constant CLASS_BOX, for obex classes
which can instantiate inside of a Max patcher (e.g. boxes, UI objects, etc.), or the constant
CLASS_NOBOX, for classes which will only be used internally. Developers can define their
own name spaces as well, but this functionality is currently undocumented.
classname The name of the class to be looked up (case free)

Returns

If successful, this function returns the class's data pointer. Otherwise, it returns NULL.

36.2.4.7 t_max_err class_free ( t_class ∗ c )

Frees a previously defined object class.

This function is not typically used by external developers.
Parameters
c The class pointer

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by jit_class_free().

36.2.4.8 long class_is_ui ( t_class ∗ c )

Determine if a class is a user interface object.

Parameters
c The class pointer.

Returns

True is the class defines a user interface object, otherwise false.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

210 Module Documentation

36.2.4.9 t_symbol∗ class_nameget ( t_class ∗ c )

Retrieves the name of a class, given the class's pointer.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.2 Classes 211

Parameters
c The class pointer

Returns

If successful, this function returns the name of the class as a t_symbol ∗.

Referenced by jit_class_nameget().

36.2.4.10 t_class∗ class_new ( C74_CONST char ∗ name, C74_CONST method mnew, C74_CONST method mfree, long
size, C74_CONST method mmenu, short type, ... )

Initializes a class by informing Max of its name, instance creation and free functions, size and argument types.
Developers wishing to use obex class features (attributes, etc.) must use class_new() instead of the traditional
setup() function.
Parameters
name The class's name, as a C-string
mnew The instance creation function
mfree The instance free function
size The size of the object's data structure in bytes. Usually you use the C sizeof operator here.
mmenu Obsolete - pass NULL. In Max 4 this was a function pointer for UI objects called when the
user created a new object of the class from the Patch window's palette.
type A standard Max type list as explained in Chapter 3 of the Writing Externals in Max document
(in the Max SDK). The final argument of the type list should be a 0. Generally, obex objects
have a single type argument, A_GIMME, followed by a 0.

Returns

This function returns the class pointer for the new object class. This pointer is used by numerous other
functions and should be stored in a global or static variable.

Referenced by ext_main(), and jit_class_new().

36.2.4.11 long class_obexoffset_get ( t_class ∗ c )

Retrieves the byte-offset of the obex member of the class's data structure.
Parameters
c The class pointer

Returns

This function returns the byte-offset of the obex member of the class's data structure.

36.2.4.12 void class_obexoffset_set ( t_class ∗ c, long offset )

Registers the byte-offset of the obex member of the class's data structure with the previously defined object class.
Use of this function is required for obex-class objects. It must be called from main().

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

212 Module Documentation

Parameters
c The class pointer
offset The byte-offset to the obex member of the object's data structure. Conventionally, the macro
calcoffset is used to calculate the offset.

Referenced by ext_main().

36.2.4.13 t_max_err class_register ( t_symbol ∗ name_space, t_class ∗ c )

Registers a previously defined object class.

This function is required, and should be called at the end of main().
Parameters
name_space The desired class's name space. Typically, either the constant CLASS_BOX, for obex classes
which can instantiate inside of a Max patcher (e.g. boxes, UI objects, etc.), or the constant
CLASS_NOBOX, for classes which will only be used internally. Developers can define their
own name spaces as well, but this functionality is currently undocumented.
c The class pointer

Returns

This function returns the error code MAX_ERR_NONE if successful, or one of the other error codes defined
in e_max_errorcodes if unsuccessful.

Referenced by ext_main(), and jit_class_register().

36.2.4.14 t_max_err class_subclass ( t_class ∗ superclass, t_class ∗ subclass )

Define a subclass of an existing class.

First call class_new on the subclass, then pass in to class_subclass. If constructor or destructor are NULL will use
the superclass constructor.
Parameters
superclass The superclass pointer.
subclass The subclass pointer.

Returns

A Max error code

36.2.4.15 t_object∗ class_super_construct ( t_class ∗ c, ... )

Call super class constructor.

Use this instead of object_alloc if you want to call the super class constructor, but allocating enough memory for
subclass.
Parameters
c The (sub)class pointer.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.2 Classes 213

... Args to super class constructor.

Returns

initialized object instance

36.2.4.16 BEGIN_USING_C_LINKAGE void C74_EXPORT ext_main ( void ∗ r )

ext_main() is the entry point for an extern to be loaded, which all externs must implement this shared/common
prototype ensures that it will be exported correctly on all platforms.
Parameters
r Pointer to resources for the external, if applicable.

See also

Anatomy of a Max Object

Version

Introduced in Max 6.1.9

References A_CANT, A_FLOAT, A_GIMME, A_LONG, addbang(), addfloat(), addint(), addmess(), attr_offset_←-
array_new(), attr_offset_new(), ATTR_SET_OPAQUE, ATTR_SET_OPAQUE_USER, calcoffset, class_addattr(),
class_addmethod(), CLASS_BOX, class_new(), class_obexoffset_set(), class_register(), object_obex_dumpout(),
object_obex_quickref(), and setup().

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

214 Module Documentation

Here is the call graph for this function:

addbang

addfloat

addint

addmess

attr_offset_array_new

attr_offset_new

class_addattr
ext_main
class_addmethod

class_new

class_obexoffset_set

class_register

object_obex_dumpout

object_obex_quickref

setup

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.3 Old-Style Classes 215

36.3 Old-Style Classes

Collaboration diagram for Old-Style Classes:

Classes Old-Style Classes

Functions

• BEGIN_USING_C_LINKAGE void setup (t_messlist ∗∗ident, method makefun, method freefun, t_getbytes←-
_size size, method menufun, short type,...)
Use the setup() function to initialize your class by informing Max of its size, the name of your functions that create and
destroy instances, and the types of arguments passed to the instance creation function.
• void addmess (method f, char ∗s, short type,...)
Use addmess() to bind a function to a message other than the standard ones covered by addbang(), addint(), etc.
• void addbang (method f)
Used to bind a function to the common triggering message bang.
• void addint (method f)
Use addint() to bind a function to the int message received in the leftmost inlet.
• void addfloat (method f)
Use addfloat() to bind a function to the float message received in the leftmost inlet.
• void addinx (method f, short n)
Use addinx() to bind a function to a int message that will be received in an inlet other than the leftmost one.
• void addftx (method f, short n)
Use addftx() to bind a function to a float message that will be received in an inlet other than the leftmost one.
• void ∗ newobject (void ∗maxclass)
Use newobject to allocate the space for an instance of your class and initialize its object header.
• void freeobject (t_object ∗op)
Release the memory used by a Max object.
• void ∗ newinstance (t_symbol ∗s, short argc, t_atom ∗argv)
Make a new instance of an existing Max class.
• void alias (char ∗name)
Use the alias function to allow users to refer to your object by a name other than that of your shared library.
• void class_setname (char ∗obname, char ∗filename)
Use class_setname() to associate you object's name with it's filename on disk.
• void ∗ typedmess (t_object ∗op, t_symbol ∗msg, short argc, t_atom ∗argp)
Send a typed message directly to a Max object.
• method getfn (t_object ∗op, t_symbol ∗msg)
Use getfn() to send an untyped message to a Max object with error checking.
• method egetfn (t_object ∗op, t_symbol ∗msg)
Use egetfn() to send an untyped message to a Max object that always works.
• method zgetfn (t_object ∗op, t_symbol ∗msg)
Use zgetfn() to send an untyped message to a Max object without error checking.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

216 Module Documentation

36.3.1 Detailed Description

36.3.2 Function Documentation

36.3.2.1 void addbang ( method f )

Used to bind a function to the common triggering message bang.

Parameters
f Function to be the bang method.

Referenced by ext_main(), max_jit_classex_mop_wrap(), and max_ob3d_setup().

36.3.2.2 void addfloat ( method f )

Use addfloat() to bind a function to the float message received in the leftmost inlet.
Parameters
f Function to be the int method.

Referenced by ext_main().

36.3.2.3 void addftx ( method f, short n )

Use addftx() to bind a function to a float message that will be received in an inlet other than the leftmost one.
Parameters
f Function to be the float method.
n Number of the inlet connected to this method. 1 is the first inlet to the right of the left inlet.

Remarks

This correspondence between inlet locations and messages is not automatic, but it is strongly suggested that
you follow existing practice. You must set the correspondence up when creating an object of your class with
proper use of intin and floatin in your instance creation function New Instance Routine.

36.3.2.4 void addint ( method f )

Use addint() to bind a function to the int message received in the leftmost inlet.
Parameters
f Function to be the int method.

Referenced by ext_main().

36.3.2.5 void addinx ( method f, short n )

Use addinx() to bind a function to a int message that will be received in an inlet other than the leftmost one.
Parameters

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.3 Old-Style Classes 217

f Function to be the int method.

n Number of the inlet connected to this method. 1 is the first inlet to the right of the left inlet.

Remarks

This correspondence between inlet locations and messages is not automatic, but it is strongly suggested that
you follow existing practice. You must set the correspondence up when creating an object of your class with
proper use of intin and floatin in your instance creation function New Instance Routine.

36.3.2.6 void addmess ( method f, char ∗ s, short type, ... )

Use addmess() to bind a function to a message other than the standard ones covered by addbang(), addint(), etc.
Parameters
f Function you want to be the method.
s C string defining the message.
type The first of one or more integers from e_max_atomtypes specifying the arguments to the
message.
... Any additional types from e_max_atomtypes for additonal arguments.

See also

Anatomy of a Max Object

Referenced by ext_main(), max_addmethod_defer(), max_addmethod_defer_low(), max_addmethod_usurp(),

max_addmethod_usurp_low(), max_jit_classex_addattr(), max_jit_classex_mop_wrap(), max_jit_classex_setup(),
max_jit_classex_standard_wrap(), and max_ob3d_setup().

36.3.2.7 void alias ( char ∗ name )

Use the alias function to allow users to refer to your object by a name other than that of your shared library.
Parameters
name An alternative name for the user to use to make an object of your class.

36.3.2.8 void class_setname ( char ∗ obname, char ∗ filename )

Use class_setname() to associate you object's name with it's filename on disk.
Parameters
obname A character string with the name of your object class as it appears in Max.
filename A character string with the name of your external's file as it appears on disk.

36.3.2.9 method egetfn ( t_object ∗ op, t_symbol ∗ msg )

Use egetfn() to send an untyped message to a Max object that always works.
Parameters

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

218 Module Documentation

op Receiver of the message.

msg Message selector.

Returns

egetfn returns a pointer to the method bound to the message selector msg in the receiver's message list. If
the method can't be found, a pointer to a do-nothing function is returned.

36.3.2.10 void freeobject ( t_object ∗ op )

Release the memory used by a Max object.

freeobject() calls an object's free function, if any, then disposes the memory used by the object itself. freeobject()
should be used on any instance of a standard Max object data structure, with the exception of Qelems and Atombufs.
Clocks, Binbufs, Proxies, Exprs, etc. should be freed with freeobject().
Parameters
op The object instance pointer to free.

Remarks

This function can be replaced by the use of object_free(). Unlike freeobject(), object_free() checkes to make
sure the pointer is not NULL before trying to free it.

See also

newobject()
object_free()

Referenced by max_jit_obex_gimmeback(), and max_jit_obex_gimmeback_dumpout().

36.3.2.11 method getfn ( t_object ∗ op, t_symbol ∗ msg )

Use getfn() to send an untyped message to a Max object with error checking.
Parameters
op Receiver of the message.
msg Message selector.

Returns

getfn returns a pointer to the method bound to the message selector msg in the receiver's message list. It
returns 0 and prints an error message in Max Window if the method can't be found.

36.3.2.12 void∗ newinstance ( t_symbol ∗ s, short argc, t_atom ∗ argv )

Make a new instance of an existing Max class.

Parameters

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.3 Old-Style Classes 219

s className Symbol specifying the name of the class of the instance to be created.
argc Count of arguments in argv.
argv Array of t_atoms; arguments to the class's instance creation function.

Returns

A pointer to the created object, or 0 if the class didn't exist or there was another type of error in creating the
instance.

Remarks

This function creates a new instance of the specified class. Using newinstance is equivalent to typing some-
thing in a New Object box when using Max. The difference is that no object box is created in any Patcher
window, and you can send messages to the object directly without connecting any patch cords. The mes-
sages can either be type- checked (using typedmess) or non-type-checked (using the members of the getfn
family).

This function is useful for taking advantage of other already-defined objects that you would like to use 'privately' in
your object, such as tables. See the source code for the coll object for an example of using a privately defined class.

36.3.2.13 void∗ newobject ( void ∗ maxclass )

Use newobject to allocate the space for an instance of your class and initialize its object header.
Parameters
maxclass The global class variable initialized in your main routine by the setup function.

Returns

A pointer to the new instance.

Remarks

You call newobject() when creating an instance of your class in your creation function. newobject allocates the
proper amount of memory for an object of your class and installs a pointer to your class in the object, so that
it can respond with your class's methods if it receives a message.

Referenced by max_jit_obex_new().

36.3.2.14 BEGIN_USING_C_LINKAGE void setup ( t_messlist ∗∗ ident, method makefun, method freefun,
t_getbytes_size size, method menufun, short type, ... )

Use the setup() function to initialize your class by informing Max of its size, the name of your functions that create
and destroy instances, and the types of arguments passed to the instance creation function.
Parameters
ident A global variable in your code that points to the initialized class.
makefun Your instance creation function.
freefun Your instance free function (see Chapter 7).

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

220 Module Documentation

size The size of your objects data structure in bytes. Usually you use the C sizeof operator here.
menufun No longer used. You should pass NULL for this parameter.
type The first of a list of arguments passed to makefun when an object is created.
... Any additional arguments passed to makefun when an object is created. Together with the
type parameter, this creates a standard Max type list as enumerated in e_max_atomtypes.
The final argument of the type list should be a 0.

See also

Anatomy of a Max Object

Referenced by ext_main().

36.3.2.15 void∗ typedmess ( t_object ∗ op, t_symbol ∗ msg, short argc, t_atom ∗ argp )

Send a typed message directly to a Max object.

Parameters
op Max object that will receive the message.
msg The message selector.
argc Count of message arguments in argv.
argp Array of t_atoms; the message arguments.

Returns

If the receiver object can respond to the message, typedmess() returns the result. Otherwise, an error mes-
sage will be seen in the Max window and 0 will be returned.

Remarks

typedmess sends a message to a Max object (receiver) a message with arguments. Note that the message
must be a t_symbol, not a character string, so you must call gensym on a string before passing it to typedmess.
Also, note that untyped messages defined for classes with the argument list A_CANT cannot be sent using
typedmess. You must use getfn() etc. instead.

Example:

1 //If you want to send a bang message to the object bang_me...

2 void *bangResult;
3 bangResult = typedmess(bang_me,gensym("bang"),0,0L);

Referenced by max_jit_mop_bang(), and max_ob3d_bang().

36.3.2.16 method zgetfn ( t_object ∗ op, t_symbol ∗ msg )

Use zgetfn() to send an untyped message to a Max object without error checking.
Parameters
op Receiver of the message.
msg Message selector.

Returns

zgetfn returns a pointer to the method bound to the message selector msg in the receiver's message list. It
returns 0 but doesn't print an error message in Max Window if the method can't be found.

Referenced by max_jit_attr_getdump().

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.4 Inlets and Outlets 221

36.4 Inlets and Outlets

Routines for creating and communicating with inlets and outlets.

Collaboration diagram for Inlets and Outlets:

Classes Inlets and Outlets

Functions

• void ∗ inlet_new (void ∗x, C74_CONST char ∗s)

Use inlet_new() to create an inlet that can receive a specific message or any message.
• void ∗ intin (void ∗x, short n)
Use intin() to create an inlet typed to receive only integers.
• void ∗ floatin (void ∗x, short n)
Use floatin() to create an inlet typed to receive only floats.
• void ∗ outlet_new (void ∗x, C74_CONST char ∗s)
Use outlet_new() to create an outlet that can send a specific non-standard message, or any message.
• void ∗ bangout (void ∗x)
Use bangout() to create an outlet that will always send the bang message.
• void ∗ intout (void ∗x)
Use intout() to create an outlet that will always send the int message.
• void ∗ floatout (void ∗x)
Use floatout() to create an outlet that will always send the float message.
• void ∗ listout (void ∗x)
Use listout() to create an outlet that will always send the list message.
• void ∗ outlet_bang (void ∗o)
Use outlet_bang() to send a bang message out an outlet.
• void ∗ outlet_int (void ∗o, t_atom_long n)
Use outlet_int() to send an int message out an outlet.
• void ∗ outlet_float (void ∗o, double f)
Use outlet_float() to send a float message out an outlet.
• void ∗ outlet_list (void ∗o, t_symbol ∗s, short ac, t_atom ∗av)
Use outlet_list() to send a list message out an outlet.
• void ∗ outlet_anything (void ∗o, t_symbol ∗s, short ac, t_atom ∗av)
Use outlet_anything() to send any message out an outlet.
• void ∗ proxy_new (void ∗x, long id, long ∗stuffloc)
Use proxy_new to create a new Proxy object.
• long proxy_getinlet (t_object ∗master)
Use proxy_getinlet to get the inlet number in which a message was received.

36.4.1 Detailed Description

Routines for creating and communicating with inlets and outlets.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

222 Module Documentation

36.4.2 Function Documentation

36.4.2.1 void∗ bangout ( void ∗ x )

Use bangout() to create an outlet that will always send the bang message.
Parameters
x Your object.

Returns

A pointer to the new outlet.

Remarks

You can send a bang message out a general purpose outlet, but creating an outlet using bangout() allows Max
to type-check the connection a user might make and refuse to connect the outlet to any object that cannot
receive a bang message. bangout() returns the created outlet.

36.4.2.2 void∗ floatin ( void ∗ x, short n )

Use floatin() to create an inlet typed to receive only floats.

Parameters
x Your object.
n Location of the inlet from 1 to 9. 1 is immediately to the right of the leftmost inlet.

Returns

A pointer to the new inlet.

36.4.2.3 void∗ floatout ( void ∗ x )

Use floatout() to create an outlet that will always send the float message.
Parameters
x Your object.

Returns

A pointer to the new outlet.

36.4.2.4 void∗ inlet_new ( void ∗ x, C74_CONST char ∗ s )

Use inlet_new() to create an inlet that can receive a specific message or any message.
Parameters
x Your object.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.4 Inlets and Outlets 223

s Character string of the message, or NULL to receive any message.

Returns

A pointer to the new inlet.

Remarks

inlet_new() ceates a general purpose inlet. You can use it in circumstances where you would like special mes-
sages to be received in inlets other than the leftmost one. To create an inlet that receives a particular message,
pass the message's character string. For example, to create an inlet that receives only bang messages, do
the following
1 inlet_new (myObject,"bang");

To create an inlet that can receive any message, pass NULL for msg
1 inlet_new (myObject, NULL);

Proxies are an alternative method for general-purpose inlets that have a number of advantages. If you create
multiple inlets as shown above, there would be no way to figure out which inlet received a message. See the
discussion in Creating and Using Proxies.

36.4.2.5 void∗ intin ( void ∗ x, short n )

Use intin() to create an inlet typed to receive only integers.

Parameters
x Your object.
n Location of the inlet from 1 to 9. 1 is immediately to the right of the leftmost inlet.

Returns

A pointer to the new inlet.

Remarks

intin creates integer inlets. It takes a pointer to your newly created object and an integer n, from 1 to 9. The
number specifies the message type you'll get, so you can distinguish one inlet from another. For example, an
integer sent in inlet 1 will be of message type in1 and a floating point number sent in inlet 4 will be of type ft4.
You use addinx() and addftx() to add methods to respond to these messages.

The order you create additional inlets is important. If you want the rightmost inlet to be the have the highest number
in- or ft- message (which is usually the case), you should create the highest number message inlet first.

36.4.2.6 void∗ intout ( void ∗ x )

Use intout() to create an outlet that will always send the int message.
Parameters
x Your object.

Returns

A pointer to the new outlet.

Remarks

You can send a bang message out a general purpose outlet, but creating an outlet using bangout() allows Max
to type-check the connection a user might make and refuse to connect the outlet to any object that cannot
receive a bang message. bangout() returns the created outlet.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

224 Module Documentation

36.4.2.7 void∗ listout ( void ∗ x )

Use listout() to create an outlet that will always send the list message.
Parameters
x Your object.

Returns

A pointer to the new outlet.

36.4.2.8 void∗ outlet_anything ( void ∗ o, t_symbol ∗ s, short ac, t_atom ∗ av )

Use outlet_anything() to send any message out an outlet.

Parameters
o Outlet that will send the message.
s The message selector t_symbol∗.
ac Number of elements in the list in argv.
av Atoms constituting the list.

Returns

Returns 0 if a stack overflow occurred, otherwise returns 1.

Remarks

This function lets you send an arbitrary message out an outlet. Here are a couple of examples of its use.

First, here's a hard way to send the bang message (see outlet_bang() for an easier way):

1 outlet_anything(myOutlet, gensym("bang"), 0, NIL);

Remarks

And here's an even harder way to send a single integer (instead of using outlet_int()).
1 t_atom myNumber;
2
3 atom_setlong(&myNumber, 432);
4 outlet_anything(myOutlet, gensym("int"), 1, &myNumber);

Notice that outlet_anything() expects the message argument as a t_symbol∗, so you must use gensym() on a
character string.

If you'll be sending the same message a lot, you might call gensym() on the message string at initialization time
and store the result in a global variable to save the (significant) overhead of calling gensym() every time you want
to send a message.
Also, do not send lists using outlet_anything() with list as the selector argument. Use the outlet_list() function
instead.
Referenced by max_jit_mop_jit_matrix(), max_jit_mop_outputmatrix(), and max_jit_obex_dumpout().

36.4.2.9 void∗ outlet_bang ( void ∗ o )

Use outlet_bang() to send a bang message out an outlet.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.4 Inlets and Outlets 225

Parameters
o Outlet that will send the message.

Returns

Returns 0 if a stack overflow occurred, otherwise returns 1.

36.4.2.10 void∗ outlet_float ( void ∗ o, double f )

Use outlet_float() to send a float message out an outlet.

Parameters
o Outlet that will send the message.
f Float value to send.

Returns

Returns 0 if a stack overflow occurred, otherwise returns 1.

36.4.2.11 void∗ outlet_int ( void ∗ o, t_atom_long n )

Use outlet_int() to send an int message out an outlet.

Parameters
o Outlet that will send the message.
n Integer value to send.

Returns

Returns 0 if a stack overflow occurred, otherwise returns 1.

36.4.2.12 void∗ outlet_list ( void ∗ o, t_symbol ∗ s, short ac, t_atom ∗ av )

Use outlet_list() to send a list message out an outlet.

Parameters
o Outlet that will send the message.
s Should be NULL, but can be the _sym_list.
ac Number of elements in the list in argv.
av Atoms constituting the list.

Returns

Returns 0 if a stack overflow occurred, otherwise returns 1.

Remarks

outlet_list() sends the list specified by argv and argc out the specified outlet. The outlet must have been
created with listout or outlet_new in your object creation function (see above). You create the list as an array
of Atoms, but the first item in the list must be an integer or float.

Here's an example of sending a list of three numbers.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

226 Module Documentation

1 t_atom myList[3];
2 long theNumbers[3];
3 short i;
4
5 theNumbers[0] = 23;
6 theNumbers[1] = 12;
7 theNumbers[2] = 5;
8 for (i=0; i < 3; i++) {
9 atom_setlong(myList+i,theNumbers[i]);
10 }
11 outlet_list(myOutlet,0L,3,&myList);

Remarks

It's not a good idea to pass large lists to outlet_list that are comprised of local (automatic) variables. If the list
is small, as in the above example, there's no problem. If your object will regularly send lists, it might make
sense to keep an array of t_atoms inside your object's data structure.

36.4.2.13 void∗ outlet_new ( void ∗ x, C74_CONST char ∗ s )

Use outlet_new() to create an outlet that can send a specific non-standard message, or any message.
Parameters
x Your object.
s A C-string specifying the message that will be sent out this outlet, or NULL to indicate the
outlet will be used to send various messages. The advantage of this kind of outlet's flexibility is
balanced by the fact that Max must perform a message-lookup in real-time for every message
sent through it, rather than when a patch is being constructed, as is true for other types of
outlets. Patchers execute faster when outlets are typed, since the message lookup can be
done before the program executes.

Returns

A pointer to the new outlet.

Referenced by max_jit_mop_matrixout_new(), and max_jit_mop_setup_simple().

36.4.2.14 long proxy_getinlet ( t_object ∗ master )

Use proxy_getinlet to get the inlet number in which a message was received.
Note that the owner argument should point to your external object's instance, not a proxy object.
Parameters
master Your object.

Returns

The index number of the inlet that received the message.

Referenced by max_jit_obex_inletnumber_get().

36.4.2.15 void∗ proxy_new ( void ∗ x, long id, long ∗ stuffloc )

Use proxy_new to create a new Proxy object.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.4 Inlets and Outlets 227

Parameters
x Your object.
id A non-zero number to be written into your object when a message is received in this particular
Proxy. Normally, id will be the inlet number analogous to in1, in2 etc.
stuffloc A pointer to a location where the id value will be written.

Returns

A pointer to the new proxy inlet.

Remarks

This routine creates a new Proxy object (that includes an inlet). It allows you to identify messages based on
an id value stored in the location specified by stuffLoc. You should store the pointer returned by proxy_new()
because you'll need to free all Proxies in your object's free function using object_free().

After your method has finished, Proxy sets the stuffLoc location back to 0, since it never sees messages coming in
an object's leftmost inlet. You'll know you received a message in the leftmost inlet if the contents of stuffLoc is 0. As
of Max 4.3, stuffLoc is not always guaranteed to be a correct indicator of the inlet in which a message was received.
Use proxy_getinlet() to determine the inlet number.
Referenced by max_jit_obex_proxy_new().

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

228 Module Documentation

36.5 Data Storage

Max provides a number of ways of storing and manipulating data at a high level.
Collaboration diagram for Data Storage:

Linked List

Quick Map

String Object

Database

Symbol Object
Data Storage
Atom Array

Dictionary Passing API

Dictionary

Hash Table

Index Map

Modules

• Atom Array
Max's atomarray object is a container for an array of atoms with an interface for manipulating that array.
• Database
Max's database ( i.e.
• Dictionary
Max 5, introduced the t_dictionary structure/object.
• Hash Table
A hash table is a data structure that associates some data with a unique key.
• Index Map
An indexmap is basically a managed array of pointers, but it allows you to derive relatively quickly the index from a
pointer in the array.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.5 Data Storage 229

• Linked List
The Max t_linklist data structure is useful for maintaining ordered lists of items where you want to be able to insert
and delete items efficiently.
• Quick Map
A quickmap implements a pair of t_hashtab hash tables so that it is fast to look up a unique value for a unique key or
vice-versa.
• String Object
Max's string object is a simple wrapper for c-strings, useful when working with Max's t_dictionary, t_linklist, or t_←-
hashtab.
• Symbol Object
The symobject class is a simple object that wraps a t_symbol∗ together with a couple of additional fields.
• Dictionary Passing API
The Dictionary Passing API defines a means by which t_dictionary instances may be passed between Max objects in
a way similar to the way Jitter Matrices are passed between objects.

Typedefs

• typedef long(∗ t_cmpfn) (void ∗, void ∗)

Comparison function pointer type.

Enumerations

• enum e_max_datastore_flags {
OBJ_FLAG_OBJ, OBJ_FLAG_REF, OBJ_FLAG_DATA, OBJ_FLAG_MEMORY,
OBJ_FLAG_SILENT, OBJ_FLAG_INHERITABLE, OBJ_FLAG_ITERATING, OBJ_FLAG_DEBUG }
Flags used in linklist and hashtab objects.

36.5.1 Detailed Description

Max provides a number of ways of storing and manipulating data at a high level.
It is recommended to use Max's data storage mechanisms where possible, as Max's systems are designed for
thread-safety and integration with the rest of Max API.

36.5.2 Typedef Documentation

36.5.2.1 typedef long(∗ t_cmpfn) (void ∗, void ∗)

Comparison function pointer type.

Methods that require a comparison function pointer to be passed in use this type. It should return true or false
depending on the outcome of the comparison of the two linklist items passed in as arguments.

See also

linklist_match()
hashtab_findfirst()
indexmap_sort()

36.5.3 Enumeration Type Documentation

36.5.3.1 enum e_max_datastore_flags

Flags used in linklist and hashtab objects.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

 230 Module Documentation

Enumerator

OBJ_FLAG_OBJ free using object_free()

OBJ_FLAG_REF don't free
OBJ_FLAG_DATA don't free data or call method
OBJ_FLAG_MEMORY don't call method, and when freeing use sysmem_freeptr() instead of freeobject
OBJ_FLAG_SILENT don't notify when modified
OBJ_FLAG_INHERITABLE obexprototype entry will be inherited by subpatchers and abstractions
OBJ_FLAG_ITERATING used by linklist to signal when is inside iteration
OBJ_FLAG_DEBUG context-dependent flag, used internally for linklist debug code

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.6 Atom Array 231

36.6 Atom Array

Max's atomarray object is a container for an array of atoms with an interface for manipulating that array.
Collaboration diagram for Atom Array:

Data Storage Atom Array

Data Structures

• struct t_atomarray
The atomarray object.

Macros

• #define ATOMARRAY_FLAG_FREECHILDREN
The atomarray flags.

Functions

• BEGIN_USING_C_LINKAGE t_atomarray ∗ atomarray_new (long ac, t_atom ∗av)

Create a new atomarray object.
• void atomarray_flags (t_atomarray ∗x, long flags)
Set the atomarray flags.
• long atomarray_getflags (t_atomarray ∗x)
Get the atomarray flags.
• t_max_err atomarray_setatoms (t_atomarray ∗x, long ac, t_atom ∗av)
Replace the existing array contents with a new set of atoms Note that atoms provided to this function will be copied.
• t_max_err atomarray_getatoms (t_atomarray ∗x, long ∗ac, t_atom ∗∗av)
Retrieve a pointer to the first atom in the internal array of atoms.
• t_max_err atomarray_copyatoms (t_atomarray ∗x, long ∗ac, t_atom ∗∗av)
Retrieve a copy of the atoms in the array.
• t_atom_long atomarray_getsize (t_atomarray ∗x)
Return the number of atoms in the array.
• t_max_err atomarray_getindex (t_atomarray ∗x, long index, t_atom ∗av)
Copy an a specific atom from the array.
• void ∗ atomarray_duplicate (t_atomarray ∗x)
Create a new atomarray object which is a copy of another atomarray object.
• void ∗ atomarray_clone (t_atomarray ∗x)
Create a new atomarray object which is a full clone of another atomarray object.
• void atomarray_appendatom (t_atomarray ∗x, t_atom ∗a)
Copy a new atom onto the end of the array.
• void atomarray_appendatoms (t_atomarray ∗x, long ac, t_atom ∗av)
Copy multiple new atoms onto the end of the array.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

232 Module Documentation

• void atomarray_chuckindex (t_atomarray ∗x, long index)

Remove an atom from any location within the array.
• void atomarray_clear (t_atomarray ∗x)
Clear the array.
• void atomarray_funall (t_atomarray ∗x, method fun, void ∗arg)
Call the specified function for every item in the atom array.

36.6.1 Detailed Description

Max's atomarray object is a container for an array of atoms with an interface for manipulating that array.
It can be useful for passing lists as a single atom, such as for the return value of an A_GIMMEBACK method. It also
used frequently in when working with Max's t_dictionary object.

See also

Dictionary

36.6.2 Macro Definition Documentation

36.6.2.1 #define ATOMARRAY_FLAG_FREECHILDREN

The atomarray flags.

Currently the only flag is ATOMARRAY_FLAG_FREECHILDREN. If set via atomarray_flags() the atomarray will
free any contained A_OBJ atoms when the atomarray is freed.

36.6.3 Function Documentation

36.6.3.1 void atomarray_appendatom ( t_atomarray ∗ x, t_atom ∗ a )

Copy a new atom onto the end of the array.

Parameters
x The atomarray instance.
a A pointer to the new atom to append to the end of the array.

See also

atomarray_appendatoms()
atomarray_setatoms()

36.6.3.2 void atomarray_appendatoms ( t_atomarray ∗ x, long ac, t_atom ∗ av )

Copy multiple new atoms onto the end of the array.

Parameters
x The atomarray instance.
ac The number of new atoms to be appended to the array.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.6 Atom Array 233

av A pointer to the first of the new atoms to append to the end of the array.

See also

atomarray_appendatom()
atomarray_setatoms()

36.6.3.3 void atomarray_chuckindex ( t_atomarray ∗ x, long index )

Remove an atom from any location within the array.

The array will be resized and collapsed to fill in the gap.
Parameters
x The atomarray instance.
index The zero-based index of the atom to remove from the array.

36.6.3.4 void atomarray_clear ( t_atomarray ∗ x )

Clear the array.

Frees all of the atoms and sets the size to zero. This function does not perform a 'deep' free, meaning that any
A_OBJ atoms will not have their object's freed. Only the references to those objects contained in the atomarray will
be freed.
Parameters
x The atomarray instance.

Returns

The number of atoms in the array.

36.6.3.5 void∗ atomarray_clone ( t_atomarray ∗ x )

Create a new atomarray object which is a full clone of another atomarray object.
Parameters
x The atomarray instance which is to be copied.

Returns

A new atomarray which is copied from x.

See also

atomarray_new()

36.6.3.6 t_max_err atomarray_copyatoms ( t_atomarray ∗ x, long ∗ ac, t_atom ∗∗ av )

Retrieve a copy of the atoms in the array.

To retrieve a pointer to the contained atoms use atomarray_getatoms().

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

234 Module Documentation

Parameters
x The atomarray instance.
ac The address of a long where the number of atoms will be set.
av The address of a t_atom pointer where the atoms will be allocated and copied.

Returns

A Max error code.

Remarks

You are responsible for freeing memory allocated for the copy of the atoms returned.

1 long ac = 0;
2 t_atom *av = NULL;
3
4 atomarray_copyatoms(anAtomarray, &ac, &av);
5 if(ac && av){
6 // do something with ac and av here...
7 sysmem_freeptr(av);
8 }

See also

atomarray_getatoms()

36.6.3.7 void∗ atomarray_duplicate ( t_atomarray ∗ x )

Create a new atomarray object which is a copy of another atomarray object.

Parameters
x The atomarray instance which is to be copied.

Returns

A new atomarray which is copied from x.

See also

atomarray_new()

36.6.3.8 void atomarray_flags ( t_atomarray ∗ x, long flags )

Set the atomarray flags.

Parameters
x The atomarray instance.
flags The new value for the flags.

36.6.3.9 void atomarray_funall ( t_atomarray ∗ x, method fun, void ∗ arg )

Call the specified function for every item in the atom array.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.6 Atom Array 235

Parameters
x The atomarray instance.
fun The function to call, specified as function pointer cast to a Max method.
arg An argument that you would like to pass to the function being called.

Returns

A max error code.

Remarks

The atomarray_funall() method will call your function for every item in the list. It will pass both a pointer to
the item in the list, and any argument that you provide. The following example shows a function that could be
called by hashtab_funall().
1 void myFun(t_atom *a, void *myArg)
2 {
3 // do something with a and myArg here
4 // a is the atom in the atom array
5 }

See also

linklist_funall()
hashtab_funall()

36.6.3.10 t_max_err atomarray_getatoms ( t_atomarray ∗ x, long ∗ ac, t_atom ∗∗ av )

Retrieve a pointer to the first atom in the internal array of atoms.

This method does not copy the atoms, btu simply provides access to them. To retrieve a copy of the atoms use
atomarray_copyatoms().
Parameters
x The atomarray instance.
ac The address of a long where the number of atoms will be set.
av The address of a t_atom pointer where the address of the first atom of the array will be set.

Returns

A Max error code.

See also

atomarray_copyatoms()

36.6.3.11 long atomarray_getflags ( t_atomarray ∗ x )

Get the atomarray flags.

Parameters
x The atomarray instance.

Returns

The current value of the atomarray flags.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

236 Module Documentation

36.6.3.12 t_max_err atomarray_getindex ( t_atomarray ∗ x, long index, t_atom ∗ av )

Copy an a specific atom from the array.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.6 Atom Array 237

Parameters
x The atomarray instance.
index The zero-based index into the array from which to retrieve an atom pointer.
av The address of an atom to contain the copy.

Returns

A Max error code.

Remarks

Example:
1 {
2 t_atom a;
3
4 // fetch a copy of the second atom in a previously existing array
5 atomarray_getindex(anAtomarray, 1, &a);
6 // do something with the atom here...
7 }

36.6.3.13 t_atom_long atomarray_getsize ( t_atomarray ∗ x )

Return the number of atoms in the array.

Parameters
x The atomarray instance.

Returns

The number of atoms in the array.

36.6.3.14 BEGIN_USING_C_LINKAGE t_atomarray∗ atomarray_new ( long ac, t_atom ∗ av )

Create a new atomarray object.

Note that atoms provided to this function will be copied. The copies stored internally to the atomarray instance. You
can free the atomarray by calling object_free().
Parameters
ac The number of atoms to be initially contained in the atomarray.
av A pointer to the first of an array of atoms to initially copy into the atomarray.

Returns

Pointer to the new atomarray object.

Remarks

Note that due to the unusual prototype of this method that you cannot instantiate this object using the object←-
_new_typed() function. If you wish to use the dynamically bound creator to instantiate the object, you should
instead should use object_new() as demonstrated below. The primary reason that you might choose to instan-
tiate an atomarray using object_new() instead of atomarray_new() is for using the atomarray object in code
that is also intended to run in Max 4.
1 object_new(CLASS_NOBOX, gensym("atomarray"), argc, argv);

See also

atomarray_duplicate()

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

238 Module Documentation

36.6.3.15 t_max_err atomarray_setatoms ( t_atomarray ∗ x, long ac, t_atom ∗ av )

Replace the existing array contents with a new set of atoms Note that atoms provided to this function will be copied.
The copies stored internally to the atomarray instance.
Parameters
x The atomarray instance.
ac The number of atoms to be initially contained in the atomarray.
av A pointer to the first of an array of atoms to initially copy into the atomarray.

Returns

A Max error code.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.7 Database 239

36.7 Database

Max's database ( i.e.

Collaboration diagram for Database:

Data Storage Database

Typedefs

• typedef t_object t_database

A database object.
• typedef t_object t_db_result
A database result object.
• typedef t_object t_db_view
A database view object.

Functions

• BEGIN_USING_C_LINKAGE t_max_err db_open (t_symbol ∗dbname, const char ∗fullpath, t_database

∗∗db)
Create an instance of a database.
• t_max_err db_open_ext (t_symbol ∗dbname, const char ∗fullpath, t_database ∗∗db, long flags)
Create an instance of a database.
• t_max_err db_close (t_database ∗∗db)
Close an open database.
• t_max_err db_query (t_database ∗db, t_db_result ∗∗dbresult, const char ∗sql,...)
Execute a SQL query on the database.
• t_max_err db_query_direct (t_database ∗db, t_db_result ∗∗dbresult, const char ∗sql)
Execute a SQL query on the database.
• t_max_err db_query_silent (t_database ∗db, t_db_result ∗∗dbresult, const char ∗sql,...)
Execute a SQL query on the database, temporarily overriding the database's error logging attribute.
• t_max_err db_query_getlastinsertid (t_database ∗db, long ∗id)
Determine the id (key) number for the most recent INSERT query executed on the database.
• t_max_err db_query_table_new (t_database ∗db, const char ∗tablename)
Create a new table in a database.
• t_max_err db_query_table_addcolumn (t_database ∗db, const char ∗tablename, const char ∗columnname,
const char ∗columntype, const char ∗flags)
Add a new column to an existing table in a database.
• t_max_err db_transaction_start (t_database ∗db)
Begin a database transaction.
• t_max_err db_transaction_end (t_database ∗db)
Finalize a database transaction.
• t_max_err db_transaction_flush (t_database ∗db)

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

240 Module Documentation

Force any open transactions to close.

• t_max_err db_view_create (t_database ∗db, const char ∗sql, t_db_view ∗∗dbview)
A database view is a way of looking at a particular set of records in the database.
• t_max_err db_view_remove (t_database ∗db, t_db_view ∗∗dbview)
Remove a database view created using db_view_create().
• t_max_err db_view_getresult (t_db_view ∗dbview, t_db_result ∗∗result)
Fetch the pointer for a t_db_view's query result.
• t_max_err db_view_setquery (t_db_view ∗dbview, char ∗newquery)
Set the query used by the view.
• char ∗∗ db_result_nextrecord (t_db_result ∗result)
Return the next record from a set of results that you are walking.
• void db_result_reset (t_db_result ∗result)
Reset the interface for walking a result's record list to the first record.
• void db_result_clear (t_db_result ∗result)
Zero-out a database result.
• long db_result_numrecords (t_db_result ∗result)
Return a count of all records in the query result.
• long db_result_numfields (t_db_result ∗result)
Return a count of all fields (columns) in the query result.
• char ∗ db_result_fieldname (t_db_result ∗result, long fieldindex)
Return the name of a field specified by its index number.
• char ∗ db_result_string (t_db_result ∗result, long recordindex, long fieldindex)
Return a single value from a result according to its index and field coordinates.
• long db_result_long (t_db_result ∗result, long recordindex, long fieldindex)
Return a single value from a result according to its index and field coordinates.
• float db_result_float (t_db_result ∗result, long recordindex, long fieldindex)
Return a single value from a result according to its index and field coordinates.
• t_ptr_uint db_result_datetimeinseconds (t_db_result ∗result, long recordindex, long fieldindex)
Return a single value from a result according to its index and field coordinates.
• void db_util_stringtodate (const char ∗string, t_ptr_uint ∗date)
A utility to convert from a sql datetime string into seconds.
• void db_util_datetostring (const t_ptr_uint date, char ∗string)
A utility to convert from seconds into a sql-ready datetime string.

36.7.1 Detailed Description

Max's database ( i.e.

t_database ) support currently consists of a SQLite ( http://sqlite.org ) extension which is loaded dynam-
ically by Max at launch time. Because it is loaded dynamically, all interfacing with the sqlite object relies on Max's
message passing interface, using object_method() and related functions.
For most common database needs, a C-interface is defined in the ext_database.h header file and implemented in
the ext_database.c source file. The functions defined in this interface wrap the message passing calls and provide
a convenient means by which you can work with databases. ext_database.c is located in the 'common' folder
inside of the 'max-includes' folder. If you use any of the functions defined ext_database.h, you will need to add
ext_database.c to your project.

36.7.2 Typedef Documentation

36.7.2.1 typedef t_object t_database

A database object.
Use db_open() and db_close() to create and free database objects.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.7 Database 241

36.7.2.2 typedef t_object t_db_result

A database result object.

This is what the database object returns when a query is executed.

36.7.2.3 typedef t_object t_db_view

A database view object.

A database view wraps a query and a result for a given database, and is always updated and in-sync with the
database.

36.7.3 Function Documentation

36.7.3.1 t_max_err db_close ( t_database ∗∗ db )

Close an open database.

Parameters
db The address of the t_database pointer for your database instance. The pointer will be freed
and set NULL upon return.

Returns

An error code.

36.7.3.2 BEGIN_USING_C_LINKAGE t_max_err db_open ( t_symbol ∗ dbname, const char ∗ fullpath, t_database
∗∗ db )

Create an instance of a database.

Parameters
dbname The name of the database.
fullpath If a database with this dbname is not already open, this will specify a full path to the location
where the database is stored on disk. If NULL is passed for this argument, the database will
reside in memory only. The path should be formatted as a Max style path.
db The address of a t_database pointer that will be set to point to the new database instance. If
the pointer is not NULL, then it will be treated as a pre-existing database instance and thus
will be freed.

Returns

An error code.

36.7.3.3 t_max_err db_open_ext ( t_symbol ∗ dbname, const char ∗ fullpath, t_database ∗∗ db, long flags )

Create an instance of a database.

Parameters

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

242 Module Documentation

dbname The name of the database.

fullpath If a database with this dbname is not already open, this will specify a full path to the location
where the database is stored on disk. If NULL is passed for this argument, the database will
reside in memory only. The path should be formatted as a Max style path.
db The address of a t_database pointer that will be set to point to the new database instance. If
the pointer is not NULL, then it will be treated as a pre-existing database instance and thus
will be freed.
flags Any flags to be passed to the database backend while opening the db. At this time, DB_O←-
PEN_FLAGS_READONLY (0x01) is the only flag available.

Returns

An error code.

36.7.3.4 t_max_err db_query ( t_database ∗ db, t_db_result ∗∗ dbresult, const char ∗ sql, ... )

Execute a SQL query on the database.

Parameters
db The t_database pointer for your database instance.
dbresult The address of a t_db_result pointer. If the pointer is passed-in set to NULL then a new
dbresult will be created. If the pointer is not NULL then it is assumed to be a valid dbresult,
which will be filled in with the query results. When you are done with the dbresult you should
free it with object_free().
sql A C-string containing a valid SQL query, possibly with sprintf() formatting codes.
... If an sprintf() formatting codes are used in the sql string, these values will be interpolated into
the sql string.

Returns

An error code.

36.7.3.5 t_max_err db_query_direct ( t_database ∗ db, t_db_result ∗∗ dbresult, const char ∗ sql )

Execute a SQL query on the database.

Parameters
db The t_database pointer for your database instance.
dbresult The address of a t_db_result pointer. If the pointer is passed-in set to NULL then a new
dbresult will be created. If the pointer is not NULL then it is assumed to be a valid dbresult,
which will be filled in with the query results. When you are done with the dbresult you should
free it with object_free().
sql A C-string containing a valid SQL query.

Returns

An error code.

36.7.3.6 t_max_err db_query_getlastinsertid ( t_database ∗ db, long ∗ id )

Determine the id (key) number for the most recent INSERT query executed on the database.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.7 Database 243

Parameters
db The t_database pointer for your database instance.
id The address of a variable to hold the result on return.

Returns

An error code.

36.7.3.7 t_max_err db_query_silent ( t_database ∗ db, t_db_result ∗∗ dbresult, const char ∗ sql, ... )

Execute a SQL query on the database, temporarily overriding the database's error logging attribute.
Parameters
db The t_database pointer for your database instance.
dbresult The address of a t_db_result pointer. If the pointer is passed-in set to NULL then a new
dbresult will be created. If the pointer is not NULL then it is assumed to be a valid dbresult,
which will be filled in with the query results. When you are done with the dbresult you should
free it with object_free().
sql A C-string containing a valid SQL query, possibly with sprintf() formatting codes.
... If an sprintf() formatting codes are used in the sql string, these values will be interpolated into
the sql string.

Returns

An error code.

36.7.3.8 t_max_err db_query_table_addcolumn ( t_database ∗ db, const char ∗ tablename, const char ∗ columnname,
const char ∗ columntype, const char ∗ flags )

Add a new column to an existing table in a database.

Parameters
db The t_database pointer for your database instance.
tablename The name of the table to which the column should be added.
columnname The name to use for the new column.
columntype The SQL type for the data that will be stored in the column. For example: "INTEGER" or
"VARCHAR"
flags If you wish to specify any additional information for the column, then pass that here. Other-
wise pass NULL.

Returns

An error code.

36.7.3.9 t_max_err db_query_table_new ( t_database ∗ db, const char ∗ tablename )

Create a new table in a database.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

244 Module Documentation

Parameters
db The t_database pointer for your database instance.
tablename The name to use for the new table. The new table will be created with one column, which
holds the primary key for the table, and is named according the form {tablename}_id.

Returns

An error code.

36.7.3.10 void db_result_clear ( t_db_result ∗ result )

Zero-out a database result.

Parameters
result The t_db_result pointer for your query results.

36.7.3.11 t_ptr_uint db_result_datetimeinseconds ( t_db_result ∗ result, long recordindex, long fieldindex )

Return a single value from a result according to its index and field coordinates.
The value will be coerced from an expected datetime field into seconds.
Parameters
result The t_db_result pointer for your query results.
recordindex The zero-based index number of the record (row) in the result.
fieldindex The zero-based index number of the field (column) in the result.

Returns

The datetime represented in seconds.

36.7.3.12 char∗ db_result_fieldname ( t_db_result ∗ result, long fieldindex )

Return the name of a field specified by its index number.

Parameters
result The t_db_result pointer for your query results.
fieldindex The zero-based index number of the field (column) in the result.

Returns

A C-String with the name of the field.

36.7.3.13 float db_result_float ( t_db_result ∗ result, long recordindex, long fieldindex )

Return a single value from a result according to its index and field coordinates.
Parameters

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.7 Database 245

result The t_db_result pointer for your query results.

recordindex The zero-based index number of the record (row) in the result.
fieldindex The zero-based index number of the field (column) in the result.

Returns

The content of the specified cell from the result scanned out to a float.

36.7.3.14 long db_result_long ( t_db_result ∗ result, long recordindex, long fieldindex )

Return a single value from a result according to its index and field coordinates.
Parameters
result The t_db_result pointer for your query results.
recordindex The zero-based index number of the record (row) in the result.
fieldindex The zero-based index number of the field (column) in the result.

Returns

The content of the specified cell from the result scanned out to a long int.

36.7.3.15 char∗∗ db_result_nextrecord ( t_db_result ∗ result )

Return the next record from a set of results that you are walking.
When you are returned a result from a query of the database, the result is prepared for walking the results from the
beginning. You can also reset the result manually to the beginning of the record list by calling db_result_reset().
Parameters
result The t_db_result pointer for your query results.

Returns

An array of C-Strings with the values for every requested column (field) of a database record. To find out how
many columns are represented in the array, use db_result_numfields().

36.7.3.16 long db_result_numfields ( t_db_result ∗ result )

Return a count of all fields (columns) in the query result.

Parameters
result The t_db_result pointer for your query results.

Returns

The count of fields in the query result.

36.7.3.17 long db_result_numrecords ( t_db_result ∗ result )

Return a count of all records in the query result.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

246 Module Documentation

Parameters
result The t_db_result pointer for your query results.

Returns

The count of records in the query result.

36.7.3.18 void db_result_reset ( t_db_result ∗ result )

Reset the interface for walking a result's record list to the first record.
Parameters
result The t_db_result pointer for your query results.

36.7.3.19 char∗ db_result_string ( t_db_result ∗ result, long recordindex, long fieldindex )

Return a single value from a result according to its index and field coordinates.
Parameters
result The t_db_result pointer for your query results.
recordindex The zero-based index number of the record (row) in the result.
fieldindex The zero-based index number of the field (column) in the result.

Returns

A C-String with the content of the specified cell in the result.

36.7.3.20 t_max_err db_transaction_end ( t_database ∗ db )

Finalize a database transaction.

Parameters
db The t_database pointer for your database instance.

Returns

An error code.

36.7.3.21 t_max_err db_transaction_flush ( t_database ∗ db )

Force any open transactions to close.

Parameters
db The t_database pointer for your database instance.

Returns

An error code.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.7 Database 247

36.7.3.22 t_max_err db_transaction_start ( t_database ∗ db )

Begin a database transaction.

When you are working with a file-based database, then the database will not be flushed to disk until db_←-
transacation_end() is called. This means that you can _much_ more efficiently execute a sequence of queries
in one transaction rather than independently.
That database object reference counts transactions, so it is possible nest calls to db_transacation_start() and db←-
_transacation_end(). It is important to balance all calls with db_transacation_end() or the database contents will
never be flushed to disk.
Parameters
db The t_database pointer for your database instance.

Returns

An error code.

36.7.3.23 void db_util_datetostring ( const t_ptr_uint date, char ∗ string )

A utility to convert from seconds into a sql-ready datetime string.

Parameters
date The datetime represented in seconds.
string The address of a valid C-string whose contents will be set to a SQL-ready string format upon
return.

36.7.3.24 void db_util_stringtodate ( const char ∗ string, t_ptr_uint ∗ date )

A utility to convert from a sql datetime string into seconds.

Parameters
string A C-string containing a date and time in SQL format.
date The datetime represented in seconds upon return.

36.7.3.25 t_max_err db_view_create ( t_database ∗ db, const char ∗ sql, t_db_view ∗∗ dbview )

A database view is a way of looking at a particular set of records in the database.

This particular set of records is defined with a standard SQL query, and the view maintains a copy of the results of
the query internally. Any time the database is modified the internal result set is updated, and any objects listening
to the view are notified via object_notify().
Parameters
db The t_database pointer for your database instance.
sql A SQL query that defines the set of results provided by the view.
dbview The address of a NULL t_db_view pointer which will be set with the new view upon return.

Returns

An error code.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

248 Module Documentation

36.7.3.26 t_max_err db_view_getresult ( t_db_view ∗ dbview, t_db_result ∗∗ result )

Fetch the pointer for a t_db_view's query result.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.7 Database 249

Parameters
dbview The t_db_view pointer for your database view instance.
result The address of a pointer to a t_db_result object. This pointer will be overwritten with the
view's result pointer upon return.

Returns

An error code.

36.7.3.27 t_max_err db_view_remove ( t_database ∗ db, t_db_view ∗∗ dbview )

Remove a database view created using db_view_create().

Parameters
db The t_database pointer for your database instance for which this view was created.
dbview The address of the t_db_view pointer for the view. This pointer will be freed and set NULL
upon return.

Returns

An error code.

36.7.3.28 t_max_err db_view_setquery ( t_db_view ∗ dbview, char ∗ newquery )

Set the query used by the view.

Parameters
dbview The t_db_view pointer for your database view instance.
newquery The SQL string to define a new query for the view, replacing the old query.

Returns

An error code.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

250 Module Documentation

36.8 Dictionary

Max 5, introduced the t_dictionary structure/object.

Collaboration diagram for Dictionary:

Data Storage Dictionary

Data Structures

• struct t_dictionary_entry
A dictionary entry.
• struct t_dictionary
The dictionary object.

Functions

• t_dictionary ∗ dictionary_new (void)

Create a new dictionary object.
• t_max_err dictionary_appendlong (t_dictionary ∗d, t_symbol ∗key, t_atom_long value)
Add a long integer value to the dictionary.
• t_max_err dictionary_appendfloat (t_dictionary ∗d, t_symbol ∗key, double value)
Add a double-precision float value to the dictionary.
• t_max_err dictionary_appendsym (t_dictionary ∗d, t_symbol ∗key, t_symbol ∗value)
Add a t_symbol∗ value to the dictionary.
• t_max_err dictionary_appendatom (t_dictionary ∗d, t_symbol ∗key, t_atom ∗value)
Add a t_atom∗ value to the dictionary.
• t_max_err dictionary_appendstring (t_dictionary ∗d, t_symbol ∗key, const char ∗value)
Add a C-string to the dictionary.
• t_max_err dictionary_appendatoms (t_dictionary ∗d, t_symbol ∗key, long argc, t_atom ∗argv)
Add an array of atoms to the dictionary.
• t_max_err dictionary_appendatomarray (t_dictionary ∗d, t_symbol ∗key, t_object ∗value)
Add an Atom Array object to the dictionary.
• t_max_err dictionary_appenddictionary (t_dictionary ∗d, t_symbol ∗key, t_object ∗value)
Add a dictionary object to the dictionary.
• t_max_err dictionary_appendobject (t_dictionary ∗d, t_symbol ∗key, t_object ∗value)
Add an object to the dictionary.
• t_max_err dictionary_getlong (C74_CONST t_dictionary ∗d, t_symbol ∗key, t_atom_long ∗value)
Retrieve a long integer from the dictionary.
• t_max_err dictionary_getfloat (C74_CONST t_dictionary ∗d, t_symbol ∗key, double ∗value)
Retrieve a double-precision float from the dictionary.
• t_max_err dictionary_getsym (C74_CONST t_dictionary ∗d, t_symbol ∗key, t_symbol ∗∗value)
Retrieve a t_symbol∗ from the dictionary.
• t_max_err dictionary_getatom (C74_CONST t_dictionary ∗d, t_symbol ∗key, t_atom ∗value)

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.8 Dictionary 251

Copy a t_atom from the dictionary.

• t_max_err dictionary_getstring (C74_CONST t_dictionary ∗d, t_symbol ∗key, const char ∗∗value)
Retrieve a C-string pointer from the dictionary.
• t_max_err dictionary_getatoms (C74_CONST t_dictionary ∗d, t_symbol ∗key, long ∗argc, t_atom ∗∗argv)
Retrieve the address of a t_atom array of in the dictionary.
• t_max_err dictionary_getatoms_ext (const t_dictionary ∗d, t_symbol ∗key, long stringstosymbols, long ∗argc,
t_atom ∗∗argv)
Retrieve the address of a t_atom array in the dictionary.
• t_max_err dictionary_copyatoms (C74_CONST t_dictionary ∗d, t_symbol ∗key, long ∗argc, t_atom ∗∗argv)
Retrieve copies of a t_atom array in the dictionary.
• t_max_err dictionary_getatomarray (C74_CONST t_dictionary ∗d, t_symbol ∗key, t_object ∗∗value)
Retrieve a t_atomarray pointer from the dictionary.
• t_max_err dictionary_getdictionary (C74_CONST t_dictionary ∗d, t_symbol ∗key, t_object ∗∗value)
Retrieve a t_dictionary pointer from the dictionary.
• t_max_err dictionary_get_ex (t_dictionary ∗d, t_symbol ∗key, long ∗ac, t_atom ∗∗av, char ∗errstr)
Retrieve the address of a t_atom array of in the dictionary within nested dictionaries.
• t_max_err dictionary_getobject (C74_CONST t_dictionary ∗d, t_symbol ∗key, t_object ∗∗value)
Retrieve a t_object pointer from the dictionary.
• long dictionary_entryisstring (C74_CONST t_dictionary ∗d, t_symbol ∗key)
Test a key to set if the data stored with that key contains a t_string object.
• long dictionary_entryisatomarray (C74_CONST t_dictionary ∗d, t_symbol ∗key)
Test a key to set if the data stored with that key contains a t_atomarray object.
• long dictionary_entryisdictionary (C74_CONST t_dictionary ∗d, t_symbol ∗key)
Test a key to set if the data stored with that key contains a t_dictionary object.
• long dictionary_hasentry (C74_CONST t_dictionary ∗d, t_symbol ∗key)
Test a key to set if it exists in the dictionary.
• t_atom_long dictionary_getentrycount (C74_CONST t_dictionary ∗d)
Return the number of keys in a dictionary.
• t_max_err dictionary_getkeys (C74_CONST t_dictionary ∗d, long ∗numkeys, t_symbol ∗∗∗keys)
Retrieve all of the key names stored in a dictionary.
• void dictionary_freekeys (t_dictionary ∗d, long numkeys, t_symbol ∗∗keys)
Free memory allocated by the dictionary_getkeys() method.
• t_max_err dictionary_deleteentry (t_dictionary ∗d, t_symbol ∗key)
Remove a value from the dictionary.
• t_max_err dictionary_chuckentry (t_dictionary ∗d, t_symbol ∗key)
Remove a value from the dictionary without freeing it.
• t_max_err dictionary_clear (t_dictionary ∗d)
Delete all values from a dictionary.
• void dictionary_funall (t_dictionary ∗d, method fun, void ∗arg)
Call the specified function for every entry in the dictionary.
• t_symbol ∗ dictionary_entry_getkey (t_dictionary_entry ∗x)
Given a t_dictionary_entry∗, return the key associated with that entry.
• void dictionary_entry_getvalue (t_dictionary_entry ∗x, t_atom ∗value)
Given a t_dictionary_entry∗, return the value associated with that entry.
• void dictionary_entry_getvalues (t_dictionary_entry ∗x, long ∗argc, t_atom ∗∗argv)
Given a t_dictionary_entry∗, return the values associated with that entry.
• t_max_err dictionary_copyunique (t_dictionary ∗d, t_dictionary ∗copyfrom)
Given 2 dictionaries, copy the keys unique to one of the dictionaries to the other dictionary.
• t_max_err dictionary_getdeflong (const t_dictionary ∗d, t_symbol ∗key, t_atom_long ∗value, t_atom_long def)
Retrieve a long integer from the dictionary.
• t_max_err dictionary_getdeffloat (const t_dictionary ∗d, t_symbol ∗key, double ∗value, double def)

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

252 Module Documentation

Retrieve a double-precision float from the dictionary.

• t_max_err dictionary_getdefsym (const t_dictionary ∗d, t_symbol ∗key, t_symbol ∗∗value, t_symbol ∗def)
Retrieve a t_symbol∗ from the dictionary.
• t_max_err dictionary_getdefatom (const t_dictionary ∗d, t_symbol ∗key, t_atom ∗value, t_atom ∗def)
Retrieve a t_atom∗ from the dictionary.
• t_max_err dictionary_getdefstring (const t_dictionary ∗d, t_symbol ∗key, const char ∗∗value, char ∗def)
Retrieve a C-string from the dictionary.
• t_max_err dictionary_getdefatoms (t_dictionary ∗d, t_symbol ∗key, long ∗argc, t_atom ∗∗argv, t_atom ∗def)
Retrieve the address of a t_atom array of in the dictionary.
• t_max_err dictionary_copydefatoms (t_dictionary ∗d, t_symbol ∗key, long ∗argc, t_atom ∗∗argv, t_atom ∗def)
Retrieve copies of a t_atom array in the dictionary.
• t_max_err dictionary_dump (t_dictionary ∗d, long recurse, long console)
Print the contents of a dictionary to the Max window.
• t_max_err dictionary_copyentries (t_dictionary ∗src, t_dictionary ∗dst, t_symbol ∗∗keys)
Copy specified entries from one dictionary to another.
• t_dictionary ∗ dictionary_sprintf (C74_CONST char ∗fmt,...)
Create a new dictionary populated with values using a combination of attribute and sprintf syntax.
• t_max_err dictionary_read (char ∗filename, short path, t_dictionary ∗∗d)
Read the specified JSON file and return a t_dictionary object.
• t_max_err dictionary_write (t_dictionary ∗d, char ∗filename, short path)
Serialize the specified t_dictionary object to a JSON file.
• t_max_err dictionary_read_yaml (const char ∗filename, const short path, t_dictionary ∗∗d)
Read the specified YAML file and return a t_dictionary object.
• t_max_err dictionary_write_yaml (const t_dictionary ∗d, const char ∗filename, const short path)
Serialize the specified t_dictionary object to a YAML file.
• void postdictionary (t_object ∗d)
Print the contents of a dictionary to the Max window.

36.8.1 Detailed Description

Max 5, introduced the t_dictionary structure/object.

This is used for object prototypes, object serialization, object constructors, and many other tasks. A dictionary is
ultimately a collection of atom values assigned to symbolic keys. In addition to primitive A_LONG, A_FLOAT, and
A_SYM atom types, the A_OBJ atom type is used for t_atomarray (for a set of atoms assigned to a key), t_dictionary
(for hierarhical use), t_string (for large blocks of text which we don't wish to bloat the symbol table), and potentially
other object data types. Internally, the dictionary object uses a combination data structure of a hash table (for fast
key lookup) and a linked-list (to maintain ordering of information within the dictionary).
Dictionaries are clonable entites, but note that all the member objects of a given dictionary may not be clonable. At
the time of this writing, for example, the t_string object is not clonable, though it will be made clonable in the near
future. In order for prototype entities to be g uaranteed their passage into the constructor, they must be clonable
(currenlty a symbol conversion is in place for the t_string class).

36.8.2 Using Dictionaries

Dictionaries are used in many places in Max 5. They can be confusing in many respects. It is easy to produce
memory leaks or bugs where objects are freed twice. It is easy to confuse what type of dictionary is used for what.
This page will begin with some high level information to help understand when to free and when not to free. Then,
we will offer recipies for using dictionaries to accomplish common tasks.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.8 Dictionary 253

36.8.2.1 Understanding Dictionaries

A dictionary stores atom values under named key entries. These atoms can contain A_OBJ values. When the
dictionary is freed, any A_OBJ values that are in the dictionary will also be freed. Thus, it is easy to mistakenly free
objects twice, thus this is something to be careful about. For example, look at this code:

t_dictionary *d = dictionary_new();
t_dictionary *sd = dictionary_new();
dictionary_appenddictionary(d, gensym("subdictionary"), sd);
do_something(d);
object_free(d); // this will free *both* d and sd since sd is contained by d
// freeing "sd" here would be bad

You primarily need to keep this in mind when calling dictionary_appendobject(), dictionary_appenddictionary(), or
dictionary_appendatomarray(). So, what do you do if you need to free a dictionary but you also want to hang on to
an object that is inside of the dictionary? In this case, chuck the entry in question first. For example, let's assume
that for some reason you cannot free the "sd" dictionary in the code above. Perhaps it doesn't belong to you. But,
to do some operation you need to append it to a new dictionary. Then, do this:

void function_foo(t_dictionary *sd) {

t_dictionary *d = dictionary_new();
dictionary_appenddictionary(d, gensym("subdictionary"), sd);
do_something(d);
dictionary_chuckentry(d, gensym("subdictionary"));
object_free(d);
}

36.8.2.2 When to Free a Dictionary

So, how do you know when you need to free a dictionary? Well, generally if you make a dictionary, you need to free
it when you are done (unless you transfer ownership of the dictionary to someone else). On the other hand, if you
are passed a dictionary (i.e. as a parameter of your function or method) then it is not yours to free and you should
just use it. However, it is not always obvious that you made a dictionary vs just borrowed it.
Here are some common (and not so common) ways to make a dictionary. These functions return a new dictionary
and thus the dictionary you get should be freed when you are done, unless you pass the dictionary on to someone
else who will free it at an appropriate time. Here they are:

• dictionary_new()

• dictionary_clone()

• dictionary_read()

• dictionary_sprintf()

• dictionary_vsprintf()

• jsonreader_parse()

• jpatcher_monikerforobject()

• class_cloneprototype()

• prototype_getdictionary()

• clipboard_todictionary()

• jpatchercontroller_copytodictionary()

• probably others of course

Here are some functions that return borrowed dictionaries. These are dictionaries that you can use but you cannot
free since you do not own them. Here they are:

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

254 Module Documentation

• dictionary_prototypefromclass()

• object_refpage_get_class_info_fromclassname()

• object_refpage_get_class_info()

• object_dictionaryarg()

Finally, most functions that accept dictionaries as parameters will not assume ownership of the dictionary. Usually
the way ownership is assumed is if you add a dictionary as a subdictionary to a dictionary that you do not own.
One exception is the utility newobject_fromdictionary_delete() who's name makes it clear that the dictionary will be
deleted after calling the function.

36.8.2.3 Some Common Uses of Dictionaries

You can make a patcher by passing a dictionary to object_new_typed() when making a "jpatcher". Using atom_←-
setparse() and attr_args_dictionary() makes this relatively easy.
Use newobject_sprintf() to programmatically make an object in a patch. Actually, you don't explicitly use a dictionary
here! If you do want more control, so you can touch the dictionary to customize it, then see the next bullet.
Use dictionary_sprintf() to make a dictionary to specify a box (i.e. specify class with @maxclass attr). Then,
make another dictionary and append your box dictionary to it under the key "box" via dictionary_appenddictionary().
Finally, make your object with newobject_fromdictionary().

See also

Linked List
Hash Table

Version

5.0

36.8.3 Reading and Writing Dictionaries as JSON

36.8.3.1 Creating a Dictionary from JSON

The easiest way to get read a t_dictionary from a JSON file on disk is to use the dictionary_read() function. In some
cases you may wish have more control, such as to generate JSON but not write it to disk. For that purpose you can
create a jsonreader object as demonstrated below.

t_dictionary *d = NULL;
t_max_err err;
t_atom result[1];
t_object *jsonreader = (t_object*)object_new(_sym_nobox, _sym_jsonreader);

// assume we have an argument called ’jsontext’ which is a const char* with the JSON
// from which we wish to create a t_dictionary instance

err = (t_max_err)object_method(jsonreader, _sym_parse, jsontext, result);

if (!err) {
t_object *ro = (t_object*)atom_getobj(result);

if (ro) {
if (object_classname_compare(ro, _sym_dictionary))
d = (t_dictionary*)ro;
else
object_free(ro);
}
}
object_free(jsonreader);

// we now have a t_dictionary in d that can be used as we see fit

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.8 Dictionary 255

36.8.3.2 Creating JSON from a Dictionary

The easiest way to get write a t_dictionary to disk as JSON is to use the dictionary_write() function. In some cases
you may wish have more control, such as to generate JSON but not write it to disk. For that purpose you can create
a jsonwriter object as demonstrated below.

t_object *jsonwriter = (t_object*)object_new(_sym_nobox, _sym_jsonwriter);

t_handle json;
const char *str;

object_method(jsonwriter, _sym_writedictionary, d);

object_method(jsonwriter, _sym_getoutput, &json);

str = *json;

// now str contains our JSON serialization of the t_dictionary d

object_free(jsonwriter);

36.8.4 Function Documentation

36.8.4.1 t_max_err dictionary_appendatom ( t_dictionary ∗ d, t_symbol ∗ key, t_atom ∗ value )

Add a t_atom∗ value to the dictionary.

Parameters
d The dictionary instance.
key The name of the key used to index the new value. All keys must be unique. If the key name
already exists, then the existing value associated with the key will be freed prior to the new
value's assignment.
value The new value to append to the dictionary.

Returns

A Max error code.

36.8.4.2 t_max_err dictionary_appendatomarray ( t_dictionary ∗ d, t_symbol ∗ key, t_object ∗ value )

Add an Atom Array object to the dictionary.

Note that from this point on that you should not free the t_atomarray∗, because the atomarray is now owned by the
dictionary, and freeing the dictionary will free the atomarray as discussed in When to Free a Dictionary.
Parameters
d The dictionary instance.
key The name of the key used to index the new value. All keys must be unique. If the key name
already exists, then the existing value associated with the key will be freed prior to the new
value's assignment.
value The new value to append to the dictionary.

Returns

A Max error code.

36.8.4.3 t_max_err dictionary_appendatoms ( t_dictionary ∗ d, t_symbol ∗ key, long argc, t_atom ∗ argv )

Add an array of atoms to the dictionary.

Internally these atoms will be copied into a t_atomarray object, which will be appended to the dictionary with the
given key.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

256 Module Documentation

Parameters
d The dictionary instance.
key The name of the key used to index the new value. All keys must be unique. If the key name
already exists, then the existing value associated with the key will be freed prior to the new
value's assignment.
argc The number of atoms to append to the dictionary.
argv The address of the first atom in the array to append to the dictionary.

Returns

A Max error code.

36.8.4.4 t_max_err dictionary_appenddictionary ( t_dictionary ∗ d, t_symbol ∗ key, t_object ∗ value )

Add a dictionary object to the dictionary.

Note that from this point on that you should not free the t_dictionary∗ that is being added, because the newly-added
dictionary is now owned by the dictionary to which it has been added, as discussed in When to Free a Dictionary.
Parameters
d The dictionary instance.
key The name of the key used to index the new value. All keys must be unique. If the key name
already exists, then the existing value associated with the key will be freed prior to the new
value's assignment.
value The new value to append to the dictionary.

Returns

A Max error code.

36.8.4.5 t_max_err dictionary_appendfloat ( t_dictionary ∗ d, t_symbol ∗ key, double value )

Add a double-precision float value to the dictionary.

Parameters
d The dictionary instance.
key The name of the key used to index the new value. All keys must be unique. If the key name
already exists, then the existing value associated with the key will be freed prior to the new
value's assignment.
value The new value to append to the dictionary.

Returns

A Max error code.

36.8.4.6 t_max_err dictionary_appendlong ( t_dictionary ∗ d, t_symbol ∗ key, t_atom_long value )

Add a long integer value to the dictionary.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.8 Dictionary 257

Parameters
d The dictionary instance.
key The name of the key used to index the new value. All keys must be unique. If the key name
already exists, then the existing value associated with the key will be freed prior to the new
value's assignment.
value The new value to append to the dictionary.

Returns

A Max error code.

36.8.4.7 t_max_err dictionary_appendobject ( t_dictionary ∗ d, t_symbol ∗ key, t_object ∗ value )

Add an object to the dictionary.

Note that from this point on that you should not free the t_object∗ that is being added, because the newly-added
object is now owned by the dictionary to which it has been added, as discussed in When to Free a Dictionary.
Parameters
d The dictionary instance.
key The name of the key used to index the new value. All keys must be unique. If the key name
already exists, then the existing value associated with the key will be freed prior to the new
value's assignment.
value The new value to append to the dictionary.

Returns

A Max error code.

36.8.4.8 t_max_err dictionary_appendstring ( t_dictionary ∗ d, t_symbol ∗ key, const char ∗ value )

Add a C-string to the dictionary.

Internally this uses the t_symbol object. It is useful to use the t_string in dictionaries rather than the t_symbol to
avoid bloating Max's symbol table unnecessarily.
Parameters
d The dictionary instance.
key The name of the key used to index the new value. All keys must be unique. If the key name
already exists, then the existing value associated with the key will be freed prior to the new
value's assignment.
value The new value to append to the dictionary.

Returns

A Max error code.

36.8.4.9 t_max_err dictionary_appendsym ( t_dictionary ∗ d, t_symbol ∗ key, t_symbol ∗ value )

Add a t_symbol∗ value to the dictionary.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

258 Module Documentation

Parameters
d The dictionary instance.
key The name of the key used to index the new value. All keys must be unique. If the key name
already exists, then the existing value associated with the key will be freed prior to the new
value's assignment.
value The new value to append to the dictionary.

Returns

A Max error code.

36.8.4.10 t_max_err dictionary_chuckentry ( t_dictionary ∗ d, t_symbol ∗ key )

Remove a value from the dictionary without freeing it.

Parameters
d The dictionary instance.
key The key associated with the value to delete.

Returns

A max error code.

See also

dictionary_deleteentry()

36.8.4.11 t_max_err dictionary_clear ( t_dictionary ∗ d )

Delete all values from a dictionary.

This method will free the objects in the dictionary. If freeing the objects is inappropriate or undesirable then you
should iterate through the dictionary and use dictionary_chuckentry() instead.
Parameters
d The dictionary instance.

Returns

A max error code.

See also

dictionary_getkeys()
dictionary_chuckentry()
dictionary_deleteentry()

36.8.4.12 t_max_err dictionary_copyatoms ( C74_CONST t_dictionary ∗ d, t_symbol ∗ key, long ∗ argc, t_atom ∗∗
argv )

Retrieve copies of a t_atom array in the dictionary.

The retrieved pointer of t_atoms in the dictionary has memory allocated and copied to it from within the function.
You are responsible for freeing it with sysmem_freeptr().

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.8 Dictionary 259

Parameters
d The dictionary instance.
key The key associated with the value to lookup.
argc The address of a variable to hold the number of atoms in the array.
argv The address of a variable to hold a pointer to the first atom in the array. You should initialize
this pointer to NULL prior to passing it to dictionary_copyatoms().

Returns

A Max error code.

See also

dictionary_getatoms()

36.8.4.13 t_max_err dictionary_copydefatoms ( t_dictionary ∗ d, t_symbol ∗ key, long ∗ argc, t_atom ∗∗ argv,
t_atom ∗ def )

Retrieve copies of a t_atom array in the dictionary.

The retrieved pointer of t_atoms in the dictionary has memory allocated and copied to it from within the function.
You are responsible for freeing it with sysmem_freeptr(). If the named key doesn't exist, then copy a default array of
atoms, specified as a t_atomarray∗.
Parameters
d The dictionary instance.
key The key associated with the value to lookup.
argc The address of a variable to hold the number of atoms in the array.
argv The address of a variable to hold a pointer to the first atom in the array. You should initialize
this pointer to NULL prior to passing it to dictionary_copyatoms().
def The default values specified as an instance of the t_atomarray object.

Returns

A Max error code.

See also

dictionary_getdefatoms()
dictionary_copyatoms()

36.8.4.14 t_max_err dictionary_copyentries ( t_dictionary ∗ src, t_dictionary ∗ dst, t_symbol ∗∗ keys )

Copy specified entries from one dictionary to another.

Parameters
src The source dictionary from which to copy entries.
dst The destination dictionary to which the entries will be copied.
keys The address of the first of an array of t_symbol∗ that specifies which keys to copy.

Returns

A Max error code.

See also

dictionary_copyunique()

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

260 Module Documentation

36.8.4.15 t_max_err dictionary_copyunique ( t_dictionary ∗ d, t_dictionary ∗ copyfrom )

Given 2 dictionaries, copy the keys unique to one of the dictionaries to the other dictionary.
Parameters
d A dictionary instance. This will be the destination for any values that are copied.
copyfrom A dictionary instance from which we will copy any values with unique keys.

Returns

A Max error code.

See also

dictionary_copyentries()

36.8.4.16 t_max_err dictionary_deleteentry ( t_dictionary ∗ d, t_symbol ∗ key )

Remove a value from the dictionary.

This method will free the object in the dictionary. If freeing the object is inappropriate or undesirable, use dictionary←-
_chuckentry() instead.
Parameters
d The dictionary instance.
key The key associated with the value to delete.

Returns

A max error code.

See also

dictionary_chuckentry()
dictionary_clear()

36.8.4.17 t_max_err dictionary_dump ( t_dictionary ∗ d, long recurse, long console )

Print the contents of a dictionary to the Max window.

Parameters
d The dictionary instance.
recurse If non-zero, the dictionary will be recursively unravelled to the Max window. Otherwise it will
only print the top level.
console If non-zero, the dictionary will be posted to the console rather than the Max window. On
the Mac you can view this using Console.app. On Windows you can use the free DbgView
program which can be downloaded from Microsoft.

Returns

A Max error code.

36.8.4.18 t_symbol∗ dictionary_entry_getkey ( t_dictionary_entry ∗ x )

Given a t_dictionary_entry∗, return the key associated with that entry.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

36.8 Dictionary 261

Parameters
x The dictionary entry.

Returns

The key associated with the entry.

See also

dictionary_entry_getvalue()
dictionary_funall()

36.8.4.19 void dictionary_entry_getvalue ( t_dictionary_entry ∗ x, t_atom ∗ value )

Given a t_dictionary_entry∗, return the value associated with that entry.

Parameters
x The dictionary entry.
value The address of a t_atom to which the value will be copied.

See also

dictionary_entry_getkey()
dictionary_funall()

36.8.4.20 void dictionary_entry_getvalues ( t_dictionary_entry ∗ x, long ∗ argc, t_atom ∗∗ argv )

Given a t_dictionary_entry∗, return the values associated with that entry.

Parameters
x The dictionary entry.
argc The length of the returned t_atom vector.
argv The address of a t_atom vector to which the values will be copied.

See also

dictionary_entry_getkey()
dictionary_funall()

36.8.4.21 long dictionary_entryisatomarray ( C74_CONST t_dictionary ∗ d, t_symbol ∗ key )

Test a key to set if the data stored with that key contains a t_atomarray object.
Parameters
d The dictionary instance.
key The key associated with the value to test.

Returns

Returns true if the key contains a t_atomarray, otherwise returns false.

36.8.4.22 long dictionary_entryisdictionary ( C74_CONST t_dictionary ∗ d, t_symbol ∗ key )

Test a key to set if the data stored with that key contains a t_dictionary object.

Generated on Tue Dec 15 2015 09:20:55 for Max API by Doxygen

262 Module Documentation

Parameters
d The dictionary instance.
key The key associated with the value to test.

Returns

Returns true if the key contains a t_dictionary, otherwise returns false.

36.8.4.23 long dictionary_entryisstring ( C74_CONST t_dictionary ∗ d, t_symbol ∗ key )

Test a key to set if the data stored with that key contains a t_string object.
Parameters
d The dictionary instance.
key The key associated with the value to test.

Returns

Returns true if the key contains a t_string, otherwise returns false.

36.8.4.24 void dictionary_freekeys ( t_dictionary ∗ d, long numkeys, t_symbol ∗∗ keys )

Free memory allocated by the dictionary_getkeys() method.

Parameters
d The dictionary instance.
numkeys The address of a long where the number of keys retrieved will be set.
keys The address of the first of an array t_symbol pointers where the retrieved keys will be set.

Returns

A max error code.

See