VEX/VEX_VexOp.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Side Effects Software Inc
 *      477 Richmond Street West
 *      Toronto, Ontario
 *      Canada   M5V 3E7
 *      416-504-9876
 *
 * NAME:        VEX_VexOp.h ( VEX Library, C++)
 *
 * COMMENTS:    External VEX function definition
 *
 * The signature of a VEX OP function determines the parameters the function
 * expects.  The signature is composed as follows:
 *      name@parms
 * where name is the user function name and the parms are the single character
 * representations of the parameters expected.  The single character mnemonics
 * are:
 *      F       = float
 *      I       = integer
 *      S       = string
 *      V       = vector
 *      P       = vector4 (originally "point")
 *      3       = matrix3
 *      4       = matrix4
 *      B       = bsdf
 *
 * If a parameter is written to by the VexOp function, the parameter mnemonic
 * should be preceded by an ampersand (&) or an asterix (*).  The ampersand is
 * used it the value of the variable is not read by the function, while the
 * asterix is used if the variable is read and then modified.  The signature
 * specification is very important if the compiler is to work correctly.
 *
 * The compiler is "smart" in that if only one argument is written to (and not
 * read from), that argument will be flagged as the return code for the
 * function.
 *
 * Examples:
 *      Signature:      test@&IF
 *      Decoded:        int test(float)
 *
 *      Signature:      test@*IF
 *      Decoded:        void test(int &, float)
 *      Details:        The integer parameter must be set since this function
 *                      reads the argument before modifying it.
 *
 *      Signature:      test@S&VFF
 *      Decoded:        vector test(string; float, float)
 *
 * At this time VEXOps do not support variadic functions (i.e. var-args
 * functions like printf()).
 *
 */

#ifndef __VEX_VexOp__
#define __VEX_VexOp__

#include "VEX_API.h"

/// VEX operator initialization callback. When called, it should allocated
/// and initialize custom state data.
typedef void    *(*VEX_VexOpInit)();
/// VEX operator evaluation callback. When called, the data returned by the
/// VEX_VexOpInit function will be passed as the "data" argument.
typedef void     (*VEX_VexOpCallback)(int argc, void *argv[], void *data);
/// VEX operator cleanup callback. When called, it should deallocate the data.
typedef void     (*VEX_VexOpCleanup)(void *data);

//
// It's possible to give hints to the compiler as to what optimizations may be
// performed on the function.  The different levels of optimizations are:
//      0 = No optimizations may be performed on the custom function.
//      2 = If all parameters to the function are constant, then the result may
//          be pre-computed and cached.
// The only time you would want to turn off optimization is to guarantee that
// your custom function is evaluated in all cases (i.e. something like printf).
// Typically, functions used in computation can be optimized by VEX.
//
// Turning off optimization may result in an overall performance hit.
//

//
// When a function modifies only one parameter (without reading from it), the
// compiler will automatically interpret the first argument as a return code
// for the function.  However, if the function modifies multiple arguments, the
// compiler assumes that all arguments should be passed by reference.
// Sometimes, it's useful to have the first modified argument treated as a
// return code rather than an actual parameter to the function.  This behaviour
// can be forced (if all conditions are met) by passing in a true on the
// "force_return_code" parameter.
// For example, something like the function:
//      import@&IS&F
// would decode to
//      import(int &success, string, float &result)
// But, with the force_return_code argument set to true, the function would be
// interpreted as:
//      int import(string, float &result)
// which is most likely more friendly to the user.
//

#define VEX_OPTIMIZE_0          0
#define VEX_OPTIMIZE_1          1
#define VEX_OPTIMIZE_2          2

// The maximum number of arguments that a VEXOp can take
#define MAX_VEXOP_ARGS          4096

typedef enum {
    VEX_SURFACE_CONTEXT         = 0x00000001,
    VEX_DISPLACE_CONTEXT        = 0x00000002,
    VEX_LIGHT_CONTEXT           = 0x00000004,
    VEX_SHADOW_CONTEXT          = 0x00000008,
    VEX_FOG_CONTEXT             = 0x00000010,
    VEX_PHOTON_CONTEXT          = 0x00000020,
    VEX_CHOP_CONTEXT            = 0x00000100,
    VEX_POP_CONTEXT             = 0x00000400,
    VEX_SOP_CONTEXT             = 0x00000800,
    VEX_COP2_CONTEXT            = 0x00001000,
    VEX_I3D_CONTEXT             = 0x00010000,
    VEX_CVEX_CONTEXT            = 0x00020000,
    VEX_INVALID_CONTEXT         = 0x00000000
} VEX_ContextType;

// Contexts for VEX Mantra
#define VEX_SHADING_CONTEXT     (VEX_SURFACE_CONTEXT | \
                                 VEX_DISPLACE_CONTEXT | \
                                 VEX_LIGHT_CONTEXT | \
                                 VEX_SHADOW_CONTEXT | \
                                 VEX_FOG_CONTEXT | \
                                 VEX_PHOTON_CONTEXT)

// OP Contexts
#define VEX_OP_CONTEXT          (VEX_CHOP_CONTEXT | \
                                 VEX_POP_CONTEXT | \
                                 VEX_SOP_CONTEXT | \
                                 VEX_COP2_CONTEXT)

// All contexts
#define VEX_ALL_CONTEXT         (VEX_SHADING_CONTEXT | \
                                 VEX_OP_CONTEXT | \
                                 VEX_I3D_CONTEXT | \
                                 VEX_CVEX_CONTEXT)

class VEX_API VEX_VexOp {
public:
    VEX_VexOp(const char        *signature,
              VEX_VexOpCallback  evaluator,
              int                ctx_mask=(VEX_ALL_CONTEXT),
              VEX_VexOpInit      init = 0,
              VEX_VexOpCleanup   cleanup = 0,
              int                optimize_level = VEX_OPTIMIZE_2,
              bool               force_return_code=false);

    ~VEX_VexOp();

    const char          *getSignature() const   { return mySignature; }
    int                  getContextMask() const { return myContextMask; }
    VEX_VexOpInit        getInit() const        { return myInit; }
    VEX_VexOpCallback    getEvaluator() const   { return myEvaluator; }
    VEX_VexOpCleanup     getCleanup() const     { return myCleanup; }
    int                  getOptimizer() const   { return myOptimizeLevel; }

    unsigned int         getFlag(unsigned int f) const  { return myFlags&f; }
    void                 setFlag(unsigned int f)        { myFlags |= f; }
    void                 clearFlag(unsigned int f)      { myFlags &= ~f; }

    // When dealing assigning to string arguments, you must "free" the previous
    // string value by calling "stringFree".  You must set the resulting string
    // to the return code from "stringAlloc".  If you do your own memory
    // management (i.e. calling strdup() or setting strings to constant
    // values), you will most likely crash VEX.
    // For example:
    //          void
    //          vexStrCat(int argc, void *argv[], void *)
    //          {
    //              // arg[0] = result, arg[1..2] == strings to concat
    //              char        work_buf[256];
    //              VEX_VexOp::stringFree((char *)argv[0]);
    //              strcpy(work_buf, (char *)argv[1]);
    //              strcat(work_buf, (char *)argv[2]);
    //              argv[0] = VEX_VexOp::stringAlloc(work_buf);
    //          }
    //          
    static const char   *stringAlloc(const char *str);
    static void          stringFree(const char *str);

    //
    // These functions can be used to query the number of DSO's loaded by VEX
    // and the locations of the shadered objects loaded.
    //
    static int                   getNumVexOps();
    static const VEX_VexOp      *getVexOp(int idx);
    static const char           *getVexOpLocation(int idx);

protected:
    // The signature of the function call.  This is documented in the header
    // above.  The constructor will duplicate the string passed in.
    char                *mySignature;

    // Initialization, Evaluation and Cleanup callbacks
    VEX_VexOpInit        myInit;
    VEX_VexOpCallback    myEvaluator;
    VEX_VexOpCleanup     myCleanup;

    // The contexts which this VEXOp is valid for.  The mask is a bit-field
    // represented by or'ing the context defines above together.
    int                  myContextMask;
    int                  myOptimizeLevel;
    unsigned int         myFlags;
};

extern "C" {
    DLLEXPORT extern void       newVEXOp(void *);
}

#endif

---