HDK
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Pages
VEX_VexOp.h
Go to the documentation of this file.
1 /*
2  * PROPRIETARY INFORMATION. This software is proprietary to
3  * Side Effects Software Inc., and is not to be reproduced,
4  * transmitted, or disclosed in any way without written permission.
5  *
6  * NAME: VEX_VexOp.h ( VEX Library, C++)
7  *
8  * COMMENTS: External VEX function definition
9  *
10  * The signature of a VEX OP function determines the parameters the function
11  * expects. The signature is composed as follows:
12  * name@parms
13  * where name is the user function name and the parms are the single character
14  * representations of the parameters expected. The single character mnemonics
15  * are:
16  * F = float
17  * I = integer
18  * S = string
19  * V = vector
20  * P = vector4 (originally "point")
21  * 3 = matrix3
22  * 4 = matrix4
23  *
24  * Arrays of primitive types use the single character mnemonic for that
25  * type preceeded by the open square bracket ([) character. The array
26  * types are then represented as:
27  * [F = float array
28  * [I = integer array
29  * [S = string array
30  * [V = vector array
31  * [P = vector4 array
32  * [3 = matrix3 array
33  * [4 = matrix4 array
34  *
35  * If a parameter is written to by the VexOp function, the parameter mnemonic
36  * should be preceded by an ampersand (&) or an asterix (*). The ampersand is
37  * used it the value of the variable is not read by the function, while the
38  * asterix is used if the variable is read and then modified. The signature
39  * specification is very important if the compiler is to work correctly.
40  *
41  * The compiler is "smart" in that if only one argument is written to (and not
42  * read from), that argument will be flagged as the return code for the
43  * function.
44  *
45  * Examples:
46  * Signature: test@&IF
47  * Decoded: int test(float)
48  *
49  * Signature: test@*IF
50  * Decoded: void test(int &, float)
51  * Details: The integer parameter must be set since this function
52  * reads the argument before modifying it.
53  *
54  * Signature: test@S&VFF
55  * Decoded: vector test(string; float, float)
56  *
57  * Signature: test@&IF+
58  * Decoded: int test(float, ...)
59  *
60  */
61 
62 #ifndef __VEX_VexOp__
63 #define __VEX_VexOp__
64 
65 #include "VEX_API.h"
66 #include "VEX_PodTypes.h"
67 #include "VEX_VexTypes.h"
68 #include "VEX_Error.h"
69 
70 /// A structure used to provide arguments with type information to the
71 /// callback function.
72 struct VEX_VexOpArg {
73  void *myArg;
75  bool myArray;
76 };
77 
78 /// VEX operator initialization callback. When called, it should allocated
79 /// and initialize custom state data.
80 typedef void *(*VEX_VexOpInit)();
81 /// VEX operator evaluation callback. When called, the data returned by the
82 /// VEX_VexOpInit function will be passed as the "data" argument.
83 typedef void (*VEX_VexOpCallback)(int argc, void *argv[], void *data);
84 /// VEX operator evaluation callback with argument type information. This
85 /// version of the operator callback must be used for variadic functions.
86 /// When called, the data returned by the VEX_VexOpInit function will be
87 /// passed as the "data" argument.
89  int argc, VEX_VexOpArg argv[], void *data);
90 /// VEX operator cleanup callback. When called, it should deallocate the data.
91 typedef void (*VEX_VexOpCleanup)(void *data);
92 /// VEX operator completed callback. Called when a shader that evaluated a
93 /// custom operator completes.
94 typedef void (*VEX_VexOpCompleted)(void *data);
95 
96 //
97 // It's possible to give hints to the compiler as to what optimizations may be
98 // performed on the function. The different levels of optimizations are:
99 // 0 = No optimizations may be performed on the custom function.
100 // 1 = If the result of the function is unused, the function can
101 // be eliminated.
102 // 2 = If all parameters to the function are constant, then the result may
103 // be pre-computed and cached.
104 // The only time you would want to turn off optimization is to guarantee that
105 // your custom function is evaluated in all cases (i.e. something like printf).
106 // Typically, functions used in computation can be optimized by VEX.
107 //
108 // Turning off optimization may result in an overall performance hit.
109 //
110 
111 /// @def VEX_OPTIMIZE_0
112 /// Perform no optimization on the VEX function
113 /// @warning this may impact performance severely.
114 /// @def VEX_OPTIMIZE_1
115 /// If the result of the function is unused, the function can be
116 /// eliminated.
117 /// @def VEX_OPTIMIZE_2
118 // If all parameters to the function are constant, then the result may
119 // be pre-computed and cached. (preferred mode)
120 #define VEX_OPTIMIZE_0 0
121 #define VEX_OPTIMIZE_1 1
122 #define VEX_OPTIMIZE_2 2
123 
124 //
125 // When a function modifies only one parameter (without reading from it), the
126 // compiler will automatically interpret the first argument as a return code
127 // for the function. However, if the function modifies multiple arguments, the
128 // compiler assumes that all arguments should be passed by reference.
129 // Sometimes, it's useful to have the first modified argument treated as a
130 // return code rather than an actual parameter to the function. This behaviour
131 // can be forced (if all conditions are met) by passing in a true on the
132 // "force_return_code" parameter.
133 // For example, something like the function:
134 // import@&IS&F
135 // would decode to
136 // import(int &success, string, float &result)
137 // But, with the force_return_code argument set to true, the function would be
138 // interpreted as:
139 // int import(string, float &result)
140 // which is most likely more friendly to the user.
141 //
142 
143 /// Use this class to extend VEX by adding custom VEX functions.
145 public:
146  /// Function declaration
147  /// @param signature @n The function name and parameters expected
148  /// @param evaluator @n The evaluation callback
149  /// @param ctx_mask @n Which contexts this function is available in
150  /// @param init @n Initialization callback (called for every instance)
151  /// @param cleanup @n Cleanup callback
152  /// @param optimize_level @n Optimization level
153  /// @param force_return_code @n
154  /// For signatures which have multiple write-only variables, this
155  /// @c bool forces the first write-only variable to be interpreted
156  /// as a return code.
157  /// @{
158  VEX_VexOp(const UT_StringHolder &signature,
159  VEX_VexOpCallback evaluator,
160  int ctx_mask=(VEX_ALL_CONTEXT),
161  VEX_VexOpInit init = 0,
162  VEX_VexOpCleanup cleanup = 0,
163  int optimize_level = VEX_OPTIMIZE_2,
164  bool force_return_code=false);
165  VEX_VexOp(const UT_StringHolder &signature,
166  VEX_VexOpTypedCallback evaluator,
167  int ctx_mask=(VEX_ALL_CONTEXT),
168  VEX_VexOpInit init = 0,
169  VEX_VexOpCleanup cleanup = 0,
170  int optimize_level = VEX_OPTIMIZE_2,
171  bool force_return_code=false);
172  /// @}
173 
174  /// Standard destructor
175  ~VEX_VexOp();
176 
177  /// Set the completed callback, called when all evaluate calls for a
178  /// given shader invokation are finished.
180  { myCompleted = cback; }
181 
182  /// Query the signature
183  const UT_StringHolder &getSignature() const { return mySignature; }
184  /// Query the context mask
185  int getContextMask() const { return myContextMask; }
186  /// Query the initialization function
187  VEX_VexOpInit getInit() const { return myInit; }
188  /// Query the evaluation function
189  VEX_VexOpCallback getEvaluator() const { return myEvaluator; }
190  /// Query the typed evaluation function
192  { return myTypedEvaluator; }
193  /// Query the cleanup function
194  VEX_VexOpCleanup getCleanup() const { return myCleanup; }
195  /// Query the completed function
196  VEX_VexOpCompleted getCompleted() const { return myCompleted; }
197  /// Query the optimization level
198  int getOptimizer() const { return myOptimizeLevel; }
199 
200  /// @private: Internal used to query state
201  unsigned int getFlag(unsigned int f) const { return myFlags&f; }
202  /// @private: Internal used to store state
203  void setFlag(unsigned int f) { myFlags |= f; }
204  /// @private: Internal used to store state
205  void clearFlag(unsigned int f) { myFlags &= ~f; }
206 
207  /// When dealing assigning to string arguments, you must "free" the previous
208  /// string value by calling "stringFree". You must set the resulting string
209  /// to the return code from "stringAlloc". If you do your own memory
210  /// management (i.e. calling strdup() or setting strings to constant
211  /// values), you will most likely crash VEX.
212  /// For example:
213  /// @code
214  /// void
215  /// vexStrCat(int argc, void *argv[], void *)
216  /// {
217  /// // arg[0] = result, arg[1..2] == strings to concat
218  /// char work_buf[256];
219  /// VEX_VexOp::stringFree((char *)argv[0]);
220  /// strcpy(work_buf, (char *)argv[1]);
221  /// strcat(work_buf, (char *)argv[2]);
222  /// argv[0] = VEX_VexOp::stringAlloc(work_buf);
223  /// }
224  /// @endcode
225  static const char *stringAlloc(const char *str);
226  /// Function to free an allocated string
227  static void stringFree(const char *str);
228 
229  /// During execution of a callback, this method can be used to retrieve
230  /// the current VEX error log for error reporting. This method will
231  /// only operate correctly in the thread that executed the callback.
232  static VEX_ErrorLog &getErrorLog();
233 
234  /// These functions can be used to query the number of DSO's loaded by VEX
235  /// and the locations of the shared objects loaded.
236  static int getNumVexOps();
237  /// Query the Nth function
238  static const VEX_VexOp *getVexOp(int idx);
239  /// Get the path to the DSO associated with the VEX plug-in
240  static const char *getVexOpLocation(int idx);
241 
242 protected:
243  // The signature of the function call. This is documented in the header
244  // above. The constructor will duplicate the string passed in.
246 
247  // Initialization, Evaluation and Cleanup callbacks
253 
254  // The contexts which this VEXOp is valid for. The mask is a bit-field
255  // represented by or'ing the context defines above together.
258  unsigned int myFlags;
259 
260 private:
261  void construct(const UT_StringHolder &signature,
262  VEX_VexOpCallback evaluator,
263  VEX_VexOpTypedCallback typed_evaluator,
264  int ctx_mask,
265  VEX_VexOpInit init,
266  VEX_VexOpCleanup cleanup,
267  int optimize,
268  bool rcode);
269 };
270 
271 extern "C" {
272  /// Function called in DSO to install new functions
273  /// All files found in $HOUDINI_DSO_PATH/vex are automatically scanned for
274  /// this function.
275  SYS_VISIBILITY_EXPORT extern void newVEXOp(void *);
276 }
277 
278 #endif
VEX_Type
VEX variable types.
Definition: VEX_VexTypes.h:18
VEX_VexOpCompleted getCompleted() const
Query the completed function.
Definition: VEX_VexOp.h:196
#define SYS_VISIBILITY_EXPORT
VEX_VexOpCleanup getCleanup() const
Query the cleanup function.
Definition: VEX_VexOp.h:194
VEX_VexOpTypedCallback myTypedEvaluator
Definition: VEX_VexOp.h:250
typedef void(APIENTRYP PFNGLCULLFACEPROC)(GLenum mode)
int myOptimizeLevel
Definition: VEX_VexOp.h:257
VEX_Type myType
Definition: VEX_VexOp.h:74
Use this class to extend VEX by adding custom VEX functions.
Definition: VEX_VexOp.h:144
void * myArg
Definition: VEX_VexOp.h:73
#define VEX_API
Definition: VEX_API.h:11
int myContextMask
Definition: VEX_VexOp.h:256
void *(* VEX_VexOpInit)()
Definition: VEX_VexOp.h:80
#define VEX_OPTIMIZE_2
Definition: VEX_VexOp.h:122
VEX_VexOpCallback myEvaluator
Definition: VEX_VexOp.h:249
void(* VEX_VexOpTypedCallback)(int argc, VEX_VexOpArg argv[], void *data)
Definition: VEX_VexOp.h:88
VEX_VexOpInit myInit
Definition: VEX_VexOp.h:248
VEX_VexOpTypedCallback getTypedEvaluator() const
Query the typed evaluation function.
Definition: VEX_VexOp.h:191
GLfloat f
Definition: glcorearb.h:1925
void(* VEX_VexOpCallback)(int argc, void *argv[], void *data)
Definition: VEX_VexOp.h:83
const UT_StringHolder & getSignature() const
Query the signature.
Definition: VEX_VexOp.h:183
void(* VEX_VexOpCompleted)(void *data)
Definition: VEX_VexOp.h:94
VEX_VexOpCleanup myCleanup
Definition: VEX_VexOp.h:251
GLboolean * data
Definition: glcorearb.h:130
VEX_VexOpInit getInit() const
Query the initialization function.
Definition: VEX_VexOp.h:187
bool myArray
Definition: VEX_VexOp.h:75
void(* VEX_VexOpCleanup)(void *data)
VEX operator cleanup callback. When called, it should deallocate the data.
Definition: VEX_VexOp.h:91
UT_StringHolder mySignature
Definition: VEX_VexOp.h:245
unsigned int myFlags
Definition: VEX_VexOp.h:258
VEX_VexOpCompleted myCompleted
Definition: VEX_VexOp.h:252
SYS_VISIBILITY_EXPORT void newVEXOp(void *)
Definition: VEX_Example.C:149
VEX_VexOpCallback getEvaluator() const
Query the evaluation function.
Definition: VEX_VexOp.h:189
#define VEX_ALL_CONTEXT
Definition: VEX_VexTypes.h:93
int getContextMask() const
Query the context mask.
Definition: VEX_VexOp.h:185
void setCompleted(VEX_VexOpCompleted cback)
Definition: VEX_VexOp.h:179
int getOptimizer() const
Query the optimization level.
Definition: VEX_VexOp.h:198