[SESI logo]

Houdini Development Toolkit - Version 6.5

Side Effects Software Inc. 2004

Objects

Base class features

The primary purposes of OBJ_Nodes are to:

Each OBJ_Node has a single input which is defined to be its parent (in the sense of object hierarchies). This is not to be confused with the parent/child relationship in the OP directory structure (see General Operators: Classes Hierarchy).

OBJ_Node is sub-classed from OP_Network so that it can contain a sub-network of SOP_Nodes that are mainly used to define the render and display geometry of the OBJ_Node. (In some cases, lights for instance, the geometry is not actually rendered.) This makes the OBJ_Node the parent of the SOP_Nodes in the organizational sense which, again, should be kept distinct from an object being the parent of another object in the object hierarchy.

Each object has parameters which define a matrix containing a transformation relative to its parent. This matrix is the local transformation matrix. Each object also has a world transformation matrix which combines all the local transformation matrices from the root of the object hierarchy to that object, resulting in a matrix that specifies the object's transformation relative to the world origin.

When you ask an OBJ_Node to cook, it cooks its parent object to get its world transform, and combines it with its own local transform to generate a global transform. Thus the OP input and dependency structure is being used to efficiently manage the generation of object transformations.

The objects also contain many parameters that are used in rendering the object scene. For instance, geometry objects have parameters which control the materials and shaders used in ray-tracing the object. Camera objects have parameters that specify a viewing frustum that can be used in specifying the viewpoint to be rendered.

To make things even more confusing, there is yet another hierarchy to be aware of, when it comes to OBJ_Nodes: the class hierarchy. Since many types of objects share common characteristics, they have been designed so that one type of OBJ_Node can be derived from another, and will inherit all the parameters of the first object. For example, camera objects are based on geometry objects, and therefore contain all the transform and rendering parameters of the geometry objects, and add the camera-specific parameters that are found in the folders labeled: "Viewing", "Crop", and "Rotoscope".


Making a new type of object

There are several reasons why you may want to make a new object type. The simplest case is that you may want to have an object that behaves exactly like an existing object, but has a different icon, or a different default SOP network, or different UI for its parameter dialogs. In more complicated cases, you may wish that the object have new parameters, or that it compute its transform differently.

See the examples in $H/toolkit/samples/OBJ for details.


Methods

virtual OBJ_Node *getParentObject();
void setParentObject(OBJ_Node *node);

These access method deal with the parent object of the object. This is the parent in the object hierarchy. (Contrast this with calling getParent() on an object. It returns you the OP_Network named "/obj".)

virtual OBJ_OBJECT_TYPE getObjectType() const;

For various purposes (including rendering and viewing), houdini needs to be able to determine the type of each OBJ_Node object. getObjectType() is used for this purpose. It returns a bitfield which is a combination of the five basic object types currently supported:

The result of the bitfield basically declares how far down the class hierarchy the object is, and allows houdini to make certain assumptions about available virtual methods and parameters. For instance, a light returns OBJ_GEOMETRY | OBJ_CAMERA | OBJ_LIGHT from its getObjectType method. That means that when houdini can use that object to specify a viewpoint for the viewport, and therefor it can be included in the camera menu above the viewport.

While getObjectType() is virtual, it is unsafe to override it without making appropriate changes to houdini's source code. (ie don't override it. Just subclass from any existing OBJ_Node type, and you'll inherit the appropriate getObjectType method)

virtual void getTransform(UT_Matrix4 &xform, OP_Context &context);

This method is obsolete and shouldn't be used. It will not exist in houdini 2.0. Use the one described immediately below, instead.

virtual UT_Matrix4 &getTransform(OP_Context &context);

This method returns the Matrix with the local transform of the object in the specified context. By default, it is returning the value of myXform after cooking the object. So if you change how myXform is computed in the object's cookMe method, getTransform will pick up that change correctly.

virtual UT_Matrix4 &getWorldTransform(OP_Context &context);

This method returns the global transform of an object. By default, it is returning the value of myWorldXform after cooking the object. So if you change how myWorldXform is computed in the object's cookMe method, getWorldTransform will pick up that change correctly.

virtual UT_Matrix4 &getIWorldTransform(OP_Context &context);

This method returns the inverse of the global transform of an object. By default, it is returning the value of myIWorldXform after cooking the object. So if you change how myIWorldXform is computed in the object's cookMe method, getIWorldTransform will pick up that change correctly.

virtual int getRelativeTransform(OP_Node &to, UT_Matrix4 &xform, OP_Context &context);

This function computes the transform required to go from this object to the object specified in the to argument in the given context.

getDisplaySopPtr();
getRenderSopPtr();

These methods return a pointer to the contained sop which has its display flag or render flag set, respectively.

Note: You may need to call getGeometryInstance() or getParticleInstance() (described below) before calling these two if you're trying to get the same geometry that is rendered or displayed for that object.

OBJ_Node *getGeometryInstance();
OBJ_Node *getParticleObject();

These first of these methods will find the OBJ_Node that is being used as the sources of instance geometry for display and rendering; while the second finds the source of the geometry that is to be instanced at each point in this objects particle system.

The methods return a null pointer if no object is specified in the parameters or if unable to find the specified object.

void expandObjectPattern(const char *pattern, UT_String &result);

This function will expand any object group specifications in pattern to the names of all the objects in that group.


Table of Contents
Operators | Surface Operations | Particle Operations | Composite Operators | Channel Operators
Material & Texture | Objects | Command and Expression | Render Output |
Mantra Shaders | Utility Classes | Geometry Library | Image Library | Clip Library
Customizing UI | Questions & Answers

Copyright © 2004 Side Effects Software Inc.
477 Richmond Street West, Toronto, Ontario, Canada M5V 3E7