Instance Objects

Objects that are rendered repeatedly with various transforms are referred to as Instance Objects.  Each transform variation results in a rendered 'instance' of the object.

Configuring an Instance Object

Select an object from the scene as Solid A.  Object Effects dialog has two tabs for configuring instance object, on Instance Object tab check Enable option.

Instance Object Settings

Controls how the Instances are located and arranged on a surface using the surface's S, T, N basis vectors.

Edge Perimeter
Distance to a Surface's edges Instances go to.

Sets the spacing between each Instance in a Surface's S, T direction

Random Range
Randomizes the space between each Instance in a Surface's S, T, N direction

acts as 'left & right' margin specifying a rectangular area on the surface for where instance objects are located within surface boundaries.
N is single direction offsetting instance objects along the surface's N vector.

Check option then apply to use a different random number for the Spacing settings. 

Surface Base Align Vector for Lighting
Each instance object will use a average of it's vertical orientation vector (Y vector) with the surface normal it is rendered on for lighting (configured using Base Surface Normal Align from the Instance XForm tab).  This gives entire set of instance objects a consistent lighting appearance.

Alpha Test
Used with Surface Base Align Vector for Lighting option for sprite/color keyed objects.  Value (0-255) compares with alpha value from base map texture, when texture alpha < test value no color/depth pixel is rendered.   

Instance Map
Controls the location of Instance objects on a surface. A gray scale map, no Instance objects are rendered to areas on the surface corresponding to the black areas in the map. Grey to white areas in the map are where the Instance objects are rendered. Additionally the instance map can variably scale the Instance objects using a 0 - 1 factor from the map (black - white).

To set an Instance Map to use with an Instance object, select the Instance object as Solid A and in the Texture dialog choose Instance Map then Set.

Instance XForm Settings

Controls how the Instances are transformed on the Surface

xR, xG, xB
Randomizes the color of each Instance using an RGB color scale range

Ind. Color Channels
Allows xR, xG, xG range to be independent instead of maintaining RGB color proportions.

X°, Y°
Rotates Instances in a random range from ± 0° - 180° around X/Y Axis

Rotates in a random range from ± 0° - 180° relative to Base Surface Normal Align vector for each Instance location on a height mapped surface.  This vector is derived from the height map contour at the Instance location.

Scale each Instance in a random range

Center Adjust along Height Axis
Instance transforms are relative to the object's center. The center adjust moves the center vertex used for transformations. In particular when scaling it's desirable to have the Instance objects all scale "up" or rotate relative from the base. In this case the height adjust is set to -½ the height of the Instance object, this will move the transform center to the base of the Instance object.

Height Axis
Default's to the Instance object's Y orientation vector, this is relative to what is perceived to be vertical axis of the object, commonly (0, 1, 0).  To use another axis uncheck Object Relative.

Base Surface Normal Align
Note: Relevant only to instances on height mapped surfaces.  Base surface refers to surface the Instance Objects are placed on.  Setting ranges from 0-100% and represents a weighted average.  Two vectors being averaged are the surface normal at the instance object's location and the underlying base surface normal the height map surface was created from (see Height Mapping).  0% will align instances using the surface normal at the location of the instance object, 100% will align instances using base surface normal, which is constant for all instances.  

Placing Instance Objects on a Surface

Select the instance object as Solid A, select a surface from the scene as Surface A, open Surface Effects dialog and on the Instance page check Add Instance object then Apply.  A Surface can have many Instance objects.

Illustration of Instance objects placed on a planar surface with an optional instance map

Instance Objects on Height Mapped Surfaces

Base surface normal align set to 0% aligns each instance to the contour of the height map

Base surface normal align set to 100% aligns each instance to base surface normal, (0, 1, 0) show here

Base surface normal align set to 50%, average with Instance object's Y orientation vector on the height map surface