Jamoma API  0.6.0.a19
MaxAudioGraph.h
Go to the documentation of this file.
1 /** @file
2  *
3  * @ingroup audioGraphMax
4  *
5  * @brief A thin wrapper of Jamoma AudioGraph for use in the Cycling '74 Max/MSP environment.
6  *
7  * @details Includes an automated class wrapper to make Jamoma DSP object's available as objects for Max/MSP.
8  *
9  * @authors Timothy Place, Trond Lossius
10  *
11  * @copyright Copyright © 2008, Timothy Place @n
12  * This code is licensed under the terms of the "New BSD License" @n
13  * http://creativecommons.org/licenses/BSD/
14  */
15 
16 
17 #ifndef __TT_MAX_AUDIOGRAPH_H__
18 #define __TT_MAX_AUDIOGRAPH_H__
19 
20 #include "ext.h" // Max Header
21 #include "ext_obex.h" // Max Object Extensions (attributes) Header
22 #include "ext_strings.h" // String Functions
23 #include "commonsyms.h" // Common symbols used by the Max 4.5 API
24 #include "z_dsp.h" // MSP Header
25 #include "jpatcher_api.h" // Required for patcher traversal code
26 
27 #include "TTAudioGraphAPI.h" // Definitions for Jamoma AudioGraph
28 #include "maxGraph.h" // Max wrapper for Jamoma Graph. Located in Support/max
29 
30 // TYPE DEFINITIONS
31 
32 #ifndef SELF
33 #define SELF t_object*(self)
34 #endif
35 
36 typedef TTErr (*TTValidityCheckFunction)(const TTPtr data); ///< A type that can be used to store a pointer to a validity checking function.
37 
39 
40 /**
41  Type definition for an AudioGraph class wrapped as a Max external.
42  @ingroup typedefs
43  */
44 typedef struct _MaxAudioGraphWrappedClass {
45  t_class* maxClass; ///< The Max class pointer.
46  t_symbol* maxClassName; ///< The name to give the Max class.
47  TTSymbol ttClassName; ///< The name of the class as registered with the Jamoma framework.
48  TTValidityCheckFunction validityCheck; ///< A function to call to validate the context for an object before it is instantiated.
49  TTPtr validityCheckArgument; ///< An argument to pass to the validityCheck function when it is called.
50  MaxAudioGraphWrappedClassOptions* options; ///< Additional configuration options specified for the class.
52 
53 
54 /** A class representing the options of a #MaxAudioGraphWrappedClass.
55  */
57 protected:
58  TTHash* options;
59 
60 public:
61 
62  /** Constructor.
63  */
65  {
66  options = new TTHash;
67  }
68 
69 
70  /** Destructor.
71  */
73  {
74  delete options;
75  }
76 
77 
78  /** Append a new option to this class.
79  @param optionName The name of the option.
80  @param optionValue The value of the option.
81  * @return #TTErr error code if the method fails to execute, else #kTTErrNone.
82  */
83  TTErr append(const TTSymbol& optionName, const TTValue& optionValue)
84  {
85  return options->append(optionName, optionValue);
86  }
87 
88 
89  /** Loopup the value of an option. Returns an error if the requested option doesn't exist.
90  * @param optionName Name of the option.
91  * @param optionValue Used to pass back the current value of the option.
92  * @return Returns an #TTErr error code if the requested option doesn't exist, else it returns #kTTErrNone.
93  */
94  TTErr lookup(const TTSymbol& optionName, TTValue& optionValue)
95  {
96  return options->lookup(optionName, optionValue);
97  }
98 
99 };
100 
101 
102 /** A pointer to a #MaxAudioGraphWrappedClass.
103  @ingroup typedefs
104  */
106 
107 
108 /** A pointer to #MaxAudioGraphWrappedClassOptions.
109  @ingroup typedefs
110  */
112 
113 
114 // FUNCTIONS
115 
116 /**
117  Wrap an AudioGraph class as a Max class.
118  * @param ttClassName Name of the Jamoma Audio Graph class that will be wrapped.
119  * @param maxClassName Name of the resulting Max external
120  * @param c Address to a variable to hold the wrapped Max class upon return.
121  * @return #TTErr error code if the method fails to execute, else #kTTErrNone.
122  */
123 TTErr wrapAsMaxAudioGraph(TTSymbol ttClassName, char* maxClassName, MaxAudioGraphWrappedClassPtr* c);
124 
125 
126 /**
127  This version can be passed a method that is called to make sure it is okay to instantiate the class.
128  This is useful, for example, if you need to have copy-protection for your external.
129  * @param ttClassName Name of the Jamoma Audio Graph class that will be wrapped.
130  * @param maxClassName Name of the resulting Max external.
131  * @param c Address to a variable to hold the wrapped Max class upon return.
132  * @param validityCheck Pointer to a function that will return a true or false regarding whether or not it is okay to instantiate the object.
133  * @return #TTErr error code if the method fails to execute, else #kTTErrNone.
134  */
135 TTErr wrapAsMaxAudioGraph(TTSymbol ttClassName, char* maxClassName, MaxAudioGraphWrappedClassPtr* c, TTValidityCheckFunction validityCheck);
136 
137 
138 /**
139  This version can be passed a method that is called to make sure it is okay to instantiate the class.
140  This is useful, for example, if you need to have copy-protection for your external.
141  * @param ttClassName Name of the Jamoma Audio Graph class that will be wrapped.
142  * @param maxClassName Name of the resulting Max external.
143  * @param c Address to a variable to hold the wrapped Max class upon return.
144  * @param validityCheck Pointer to a function that will return a true or false regarding whether or not it is okay to instantiate the object.
145  * @param validityCheckArgument An argument that will be passed to the validity check function, or NULL if you don't wish to pass an argument.
146  * @return #TTErr error code if the method fails to execute, else #kTTErrNone.
147  */
148 TTErr wrapAsMaxAudioGraph(TTSymbol ttClassName, char* maxClassName, MaxAudioGraphWrappedClassPtr* c, TTValidityCheckFunction validityCheck, TTPtr validityCheckArgument);
149 
150 
151 // These are versions of the above, but for which additional options can be specified.
152 
153 /**
154  This version can be passed a method that is called to make sure it is okay to instantiate the class.
155  This is useful, for example, if you need to have copy-protection for your external.
156  * @param ttClassName Name of the Jamoma Audio Graph class that will be wrapped.
157  * @param maxClassName Name of the resulting Max external.
158  * @param c Address to a variable to hold the wrapped Max class upon return.
159  * @param options Pointer to additional options that will be forwarded to the wrapped object when instantiated.
160  * @return #TTErr error code if the method fails to execute, else #kTTErrNone.
161  */
163 
164 
165 /**
166  This version can be passed a method that is called to make sure it is okay to instantiate the class.
167  This is useful, for example, if you need to have copy-protection for your external.
168  * @param ttClassName Name of the Jamoma Audio Graph class that will be wrapped.
169  * @param maxClassName Name of the resulting Max external.
170  * @param c Address to a variable to hold the wrapped Max class upon return.
171  * @param validityCheck Pointer to a function that will return a true or false regarding whether or not it is okay to instantiate the object.
172  * @param options Pointer to additional options that will be forwarded to the wrapped object when instantiated.
173  * @return #TTErr error code if the method fails to execute, else #kTTErrNone.
174  */
176 
177 /**
178  This version can be passed a method that is called to make sure it is okay to instantiate the class.
179  This is useful, for example, if you need to have copy-protection for your external.
180  * @param ttClassName Name of the Jamoma Audio Graph class that will be wrapped.
181  * @param maxClassName Name of the resulting Max external.
182  * @param c Address to a variable to hold the wrapped Max class upon return.
183  * @param validityCheck Pointer to a function that will return a true or false regarding whether or not it is okay to instantiate the object.
184  * @param validityCheckArgument An argument that will be passed to the validity check function, or NULL if you don't wish to pass an argument.
185  * @param options Pointer to additional options that will be forwarded to the wrapped object when instantiated.
186  */
187 TTErr wrapAsMaxAudioGraph(TTSymbol ttblueClassName, char* maxClassName, MaxAudioGraphWrappedClassPtr* c, TTValidityCheckFunction validityCheck, TTPtr validityCheckArgument, MaxAudioGraphWrappedClassOptionsPtr options);
188 
189 
190 /**
191  Method called when a connection from an upstream node is dropped.
192  * @param self This Max object.
193  * @param inletNumber The inlet of this object who is now loosing a connection.
194  * @param sourceMaxObject The upstream (source) object who is now disconnecting.
195  * @param sourceOutletNumber The outlet of the source object that is now being disconnected.
196  * @return #TTErr error code if the method fails to execute, else #kTTErrNone.
197  */
198 TTErr MaxAudioGraphDrop(t_object* self, long inletNumber, t_object* sourceMaxObject, long sourceOutletNumber);
199 
200 
201 /**
202  Returns a pointer to the Jamoma Audio Graph object that is wrapped by this Max object.
203  * @param self This Max object.
204  * @param returnedAudioGraphObject Pointer to the wrapped Jamoma Audio Graph object.
205  * @return #TTErr error code if the method fails to execute, else #kTTErrNone.
206  */
207 TTErr MaxAudioGraphObject(t_object* self, TTAudioGraphObjectBasePtr* returnedAudioGraphObject);
208 
209 
210 /**
211  Method called when an upstream node is connected to this node.
212  * @param x This Max object.
213  * @param audioSourceObject The upstream object/node that is now connecting.
214  * @param sourceOutletNumber What outlet of the upstream object that is now connecting to this object.
215  * @return #TTErr error code if the method fails to execute, else #kTTErrNone.
216  */
217 TTErr MaxAudioGraphConnect(t_object* x, TTAudioGraphObjectBasePtr audioSourceObject, TTUInt16 sourceOutletNumber);
218 
219 
220 /**
221  Clear the list of source objects from which this object will try to pull audio
222  * @param x This Max object.
223  * @param vectorSize Initial vector size, might be overruled by subsequent process calls.
224  * @return #TTErr error code if the method fails to execute, else #kTTErrNone.
225  */
226 TTErr MaxAudioGraphReset(t_object* x, long vectorSize);
227 
228 
229 /**
230  Set up fresh connections from this object to nodes that are connected downstream.
231  * @param self This Max object.
232  * @return #TTErr error code if the method fails to execute, else #kTTErrNone.
233  */
234 TTErr MaxAudioGraphSetup(t_object* self);
235 
236 
237 #endif // __TT_MAX_AUDIOGRAPH_H__
238 
std::uint16_t TTUInt16
16 bit unsigned integer
Definition: TTBase.h:176
TTErr lookup(const TTSymbol &optionName, TTValue &optionValue)
Loopup the value of an option.
Definition: MaxAudioGraph.h:94
TTErr lookup(const TTSymbol key, TTValue &value)
Find the value for the given key.
Definition: TTHash.cpp:76
virtual ~MaxAudioGraphWrappedClassOptions()
Destructor.
Definition: MaxAudioGraph.h:72
Provides all necessary definitions for AudioGraph API.
MaxAudioGraphWrappedClassOptions()
Constructor.
Definition: MaxAudioGraph.h:64
t_symbol * maxClassName
The name to give the Max class.
Definition: MaxAudioGraph.h:46
Maintain a collection of TTValue objects indexed by TTSymbol pointers.
Definition: TTHash.h:36
MaxAudioGraphWrappedClassOptions * options
Additional configuration options specified for the class.
Definition: MaxAudioGraph.h:50
TTErr MaxAudioGraphReset(t_object *x, long vectorSize)
Clear the list of source objects from which this object will try to pull audio.
void * TTPtr
A generic pointer.
Definition: TTBase.h:248
A class representing the options of a MaxAudioGraphWrappedClass.
Definition: MaxAudioGraph.h:56
t_class * maxClass
The Max class pointer.
Definition: MaxAudioGraph.h:45
MaxAudioGraphWrappedClassOptions * MaxAudioGraphWrappedClassOptionsPtr
A pointer to MaxAudioGraphWrappedClassOptions.
Type definition for an AudioGraph class wrapped as a Max external.
Definition: MaxAudioGraph.h:44
TTErr(* TTValidityCheckFunction)(const TTPtr data)
A type that can be used to store a pointer to a validity checking function.
Definition: MaxAudioGraph.h:36
TTErr append(const TTSymbol &optionName, const TTValue &optionValue)
Append a new option to this class.
Definition: MaxAudioGraph.h:83
MaxAudioGraphWrappedClass * MaxAudioGraphWrappedClassPtr
A pointer to a MaxAudioGraphWrappedClass.
The TTSymbol class is used to represent a string and efficiently pass and compare that string...
Definition: TTSymbol.h:26
TTErr append(const TTSymbol key, const TTValue &value)
Insert an item into the hash table.
Definition: TTHash.cpp:70
TTErr MaxAudioGraphObject(t_object *self, TTAudioGraphObjectBasePtr *returnedAudioGraphObject)
Returns a pointer to the Jamoma Audio Graph object that is wrapped by this Max object.
TTErr wrapAsMaxAudioGraph(TTSymbol ttClassName, char *maxClassName, MaxAudioGraphWrappedClassPtr *c)
Wrap an AudioGraph class as a Max class.
TTPtr validityCheckArgument
An argument to pass to the validityCheck function when it is called.
Definition: MaxAudioGraph.h:49
TTErr
Jamoma Error Codes Enumeration of error codes that might be returned by any of the TTBlue functions a...
Definition: TTBase.h:342
The TTAudioGraphObjectBase wraps a TTDSP object such that it is possible to build a dynamic graph of ...
TTErr MaxAudioGraphConnect(t_object *x, TTAudioGraphObjectBasePtr audioSourceObject, TTUInt16 sourceOutletNumber)
Method called when an upstream node is connected to this node.
TTErr MaxAudioGraphDrop(t_object *self, long inletNumber, t_object *sourceMaxObject, long sourceOutletNumber)
Method called when a connection from an upstream node is dropped.
TTValidityCheckFunction validityCheck
A function to call to validate the context for an object before it is instantiated.
Definition: MaxAudioGraph.h:48
[doxygenAppendixC_copyExample]
Definition: TTValue.h:34
TTSymbol ttClassName
The name of the class as registered with the Jamoma framework.
Definition: MaxAudioGraph.h:47
TTErr MaxAudioGraphSetup(t_object *self)
Set up fresh connections from this object to nodes that are connected downstream. ...