IFD is the scene description format produced by Houdini and consumed by mantra to produce a rendered image or animation sequence. The IFD file contains a complete description of the scene and how to render it.
Structure of an IFD
Typically comments and the ray_version command
Retained Object Definitions
Local Object Definitions (Geometry, Space, Light, Atmosphere or Instance)
Optional: additional frames
Geometry may be declared anywhere in the IFD, as long as it’s declared prior to being referenced.
Mantra uses a subset of the hscript scripting language to process IFDs. So some constructs like variable expansion,
if statements, looping constructs, expression evaluation can be used in IFD.
Loads the OTL given by the path. This allows assets within OTLs to be properly referenced by mantra.
Begins definition of an object. The object_type may be one of:
Each object has properties associated which determine the rendering behavior.
There are three ways of specifying geometry in mantra.
End declaration of an object
Sets a global or object property. Each object has different properties which may be set using this command.
Defines the output image for rendering a single frame. Image planes are defined using the
This command was replaced in Houdini 9.1 with
For versions prior to 9.1, the
Any global or exported VEX variable may be used as the
This command was replaced in Houdini 9.1 with
ray_property plane pfilter "sinc 2 2" ray_property plane gamma 1.7
For versions prior to 9.1, sets the value for an image plane defined by
Specifies a transformation matrix.
This statement may be followed by an arbitrary number of
Specifies geometry for an instance object. This is the geometry which will be rendered for the instance. The geometry_object parameter refers to a geometry object which must already be defined in the IFD.
Only one of
Defines a procedural function for generating geometry. The -m/-M options are used to define a bounding box for the procedural geometry and may be used to optimize rendering (since mantra may not have to generate any procedural geometry if the bounding box is not rendered). Procedurals may be written by users using the HDK.
This command is deprecated in favor of the new
For versions prior to 9.1, declares a user defined property. These properties may be referenced by “user:name” from within VEX shaders.
The type should be one of
The optional -v argument may be used to specify an arbitrary vector size for the property. The property’s value should be specified when the option is declared.
Declares a user defined property.
ray_declare object int my_property 42
Specifies the time (in seconds) which this frame represents. This is used as a random number seed when
Clear object definitions. Currently only:
...may be cleared. After a frame is rendered,
Sets an option of the output device in the plane settings.
ray_deviceoption int JPEG.quality 75
This command is output when you use the pre-defined image output properties. You can also use the command in IFD to set arbitrary options, such as options on a custom device:
ray_deviceoption float MYFORMAT.Option value
Image plane commands
As of Houdini 9.1 these commands are no longer the preferred method for defining image plane settings. The preferred method is now to use the
ray_property plane command to set properties. See image plane properties in the properties documentation.
These commands will be supported for some time for backwards compatibility.
Specifies the gamma correction for the image (default is 1).
Each color value is multiplied by the gain prior to being quantized.
The amount of dithering to apply. The dither is specified as a fraction of the quantization step (i.e. 0.5 will be one half of a quantization step). The option is ignored for floating point output.
The white-point of the image used during quantization.
The storage type for output. The value should be one of:
De-normalization of floating point values will cause minimal rounding of the floating point values, preventing values like 0.4999999 or 0.5000001.
Specifies the sampling filter used to composite sub-pixel samples. This determines how the individual surface samples will be composited to generate a single sub-pixel sample. The possible types are:
Specifies the pixel filter, used to combine sub-pixel samples to generate the value for the single pixel. There are several different pixel filters available.
The value for this output variable should be generated during the evaluation of
Specifying properties in IFD
Properties may be set anywhere in the IFD. If object properties are set outside of an object block, they change the default value for all objects declared after the change. For example:
ray_property object shadingrate 2 ray_start object # Shading rate will be "2" ray_end ray_start object # Change the shading rate to 1 ray_property object shadingrate 1 ray_end
See the list of Houdini render properties for mappings to IFD properties.
Categories vs. Masks
Categories and masks provide ways to specify a set of objects or lights.
Masks use the object name to determine membership and use the same semantics as object globbing in Houdini, for example
|Each object in mantra also may optionally have category membership assigned. These are arbitrary user tokens. Category selection works using a simple boolean algebra on the category names to determine membership. Category patterns are formed using simple expressions|
Multiple expressions may be joined by | (union) and & (intersection). Expression are processed from left to right with the intersection operator at a higher precedence than the union. No parentheses are supported.
a & b & c | d & e | f | g & h
...is equivalent to the following invalid (as parentheses are not supported) expression:
( a & b & c ) | ( d & e ) | f | ( g & h )
For example, the category pattern
- | foo will match any objects tagged with category
foo, or any uncategorized objects.
If you specify both a mask and categories, mantra uses the intersection of the two sets (that is, only objects which are in both sets).