Patch Data Type

Declaration:

patch <name> ( <component list> );

Reference:

<name>

Literal:

patch ( <component list> )

Purpose:

A patch is a NURBS surface. It may be instanced as an object in the MODEL Section. A curved or flat surface with smooth or hard edges can be created with a NURBS. A patch may be specified as a literal or as a variable. If specified as a variable, it must have a name. Any of the following components may be specified between the parentheses:

All components are specified using a keyword=value form. Components are separated by commas. Of the above components, cvs, uknots and vknots are required. Not all components are optional. The components may be specified in any order. Components which are not specified take on their default value. There may be any number of trim_regions. If any component other than trim_region is specified more than once, the last such specification will be used, and all previous ones ignored.

Example:

patch square_patch ( divisions = (8, 8),

	shader = pink,

	cvs = ( ( cv( (  1.5, 0.0, -1.5 ), 1.0 ),

	cv( (  0.5, 0.0, -1.5 ), 1.0 ),

	cv( ( -0.5, 0.0, -1.5 ), 1.0 ),

	cv( ( -1.5, 0.0, -1.5 ), 1.0 ) ),

	( cv( (  1.5, 0.0, -0.5 ), 1.0 ),

	cv( (  0.5, 0.0, -0.5 ), 1.0 ),

	cv( ( -0.5, 0.0, -0.5 ), 1.0 ),

	cv( ( -1.5, 0.0, -0.5 ), 1.0 ) ),

	( cv( (  1.5, 0.0,  0.5 ), 1.0 ),

	cv( (  0.5, 0.0,  0.5 ), 1.0 ),

	cv( ( -0.5, 0.0,  0.5 ), 1.0 ),

	cv( ( -1.5, 0.0,  0.5 ), 1.0 ) ),

	( cv( (  1.5, 0.0,  1.5 ), 1.0 ),

	cv( (  0.5, 0.0,  1.5 ), 1.0 ),

	cv( ( -0.5, 0.0,  1.5 ), 1.0 ),

	cv( ( -1.5, 0.0,  1.5 ), 1.0 ) ) )

);

active

Syntax:

active = <scalar>

Range:

0 (FALSE) or not 0 (TRUE)

Default:

TRUE

Purpose:

A Boolean flag that controls whether the patch is visible or not.

Comments:

This component may be animated. This is provided so you no longer have to scale objects in an animation to 0 or translate them outside the scene for frames in which they shouldn’t appear.

Example:

active = FALSE

casts_shadow

Syntax:

casts_shadow = <scalar>

Range:

0 (FALSE) or not 0 (TRUE)

Default:

TRUE

Purpose:

A Boolean that controls whether or not this patch will cast a shadow.

Comments:

This component may be animated.

NoteA surface with transparent or semi-transparent shading will not cast a shadow when RayCasting.

Example:

casts_shadow = FALSE

clusters

Syntax:

clusters = (<cluster matrix list>),

Range:

N/A

Default:

None.

Purpose:

A list of cluster matrices that affect the current surface.

Comments:

A cluster matrix describes the initial position of the matrix (4X4 scalars), the type of cluster effect (JOINT or LEAF), JOINT level (or 0 if the type is LEAF), and translate, rotate, scale as 3 scalar tuples.

Example:

 clusters = (

 clm( CL_r_peak,

 1.0      ,  0.0      ,  0.0      ,  0.0      ,

 0.0      ,  1.0      ,  0.0      ,  0.0      ,

 0.0      ,  0.0      ,  1.0      ,  0.0      ,

 0.283681 ,  0.0285822, -0.5841172,  1.0      ,

 LEAF, 0,

 0.0      ,  0.0      ,  0.0      ,

 0.0      ,  0.0      ,  0.0      ,

 1.0      ,  1.0      ,  1.0      ),

 clm( CL_knot45_section0_Rwrist,

 1.0      ,  0.0      ,  0.0      ,  0.0      ,

 0.0      ,  1.0      ,  0.0      ,  0.0      ,

 0.0      ,  0.0      ,  1.0      ,  0.0      ,

 0.283681 ,  0.0285822, -0.5841172,  1.0      ,

 LEAF, 0,

 0.0      ,  0.0      ,  0.0      ,

 0.0      ,  0.0      ,  0.0      ,

 1.0      ,  1.0      ,  1.0      )

 clm( CL_cluster#10,

 1.0      ,  0.0      ,  0.0      ,  0.0      ,

 0.0      ,  1.0      ,  0.0      ,  0.0      ,

 0.0      ,  0.0      ,  1.0      ,  0.0      ,

 0.283681 ,  0.0285822, -0.5841172,  1.0      ,

 JOINT, 3,

 -0.2398842, -0.0303474,  0.0      ,

 0.0      ,  0.0      ,  0.0      ,

 1.0      ,  1.0      ,  1.0      )              ),

curvature

Syntax:

curvature = <scalar>

Range:

0 to 1. Values outside the range [0, 1] are clipped to 0 and 1 respectively.

Default:

0.96

Purpose:

This controls the threshold for adaptive subdivision.

Comments:

It may be animated. For good quality, use .90 and above. The larger the curvature value, the more the curve will be subdivided. This is ignored if uniform subdivision is being used.

Example:

curvature = 0.99

cvs

Syntax:

cvs = ( ( <cv>, <cv>, … <cv> ),

( <cv>, <cv>, … <cv> ),

.

( <cv>, <cv>, … <cv> ) )

Range:

Any collection of valid cvs (for more information about valid cvs, see the CV Data Type).

Default:

None. Must be specified.

Purpose:

This defines the control vertices for the patch.

Comments:

It may be animated. The CVs will be interpreted in the sequence

(( cv[u=0,v=0], cv[u=0,v=1], cv[u=0,v=2], cv[u=0,v=3] ),

( cv[u=1,v=0], cv[u=1,v=1], cv[u=1,v=2], cv[u=1,v=3] ),

( cv[u=2,v=0], cv[u=2,v=1], cv[u=2,v=2], cv[u=2,v=3] ),

( cv[u=3,v=0], cv[u=3,v=1], cv[u=3,v=2], cv[u=3,v=3] ))

Note that this is the same sequence as previous versions.

Example:

cvs = ( ( cv((3,0,-3),1), cv((1,0,-3),1), cv((-1,0,-3),1), cv((3,0,-3),1)),

	( cv((3,0,-1),1), cv((1,0,-1),1), cv((-1,0,-1),1), cv((-3,0,-1),1)),

	( cv((3,0, 1),1), cv((1,0,1),1), cv((-1,0, 1),1), cv((-3,0, 1),1)),

	( cv((3,0, 3),1), cv((1,0,3),1), cv((-1,0, 3),1), cv((-3,0, 3),1)),)

divisions

Syntax:

divisions = ( <scalar>, <scalar> )

Range:

See subdivide. If adaptive, then divisions takes powers of 2 in the range 1 to 128. If uniform, it uses integers greater than zero.

Default:

None. Must be specified.

Purpose:

This specifies the number of arc subdivisions.

Comments:

This component may be animated. If uniform subdivision is being used, then the first scalar specifies the number of arc subdivisions in the u direction, and the second scalar specifies the number in the v direction. If adaptive subdivision is being used, then this component specifies the minimum and maximum subdivision, respectively, to be used. Note that the minimum and maximum actually used by adaptive subdivision will be the closest power of 2 greater than or equal to that given.

Example:

divisions = ( 2, 4 )

doublesided

Syntax:

doublesided = <scalar>

Range:

0 (FALSE) or not 0 (TRUE)

Default:

TRUE; that is, the patch will be doublesided.

Purpose:

The scalar will be interpreted as a Boolean, with 0 being FALSE and any other value TRUE. If doublesided is FALSE, rendering proceeds more quickly, but only one side of the surface is rendered. For most objects other than closed surfaces, doublesided = TRUE is desirable. The reader is warned that with the raytracer, rays may strike the object from any direction.

Comments:

This component may be animated.

Example:

doublesided = FALSE

end

Syntax:

end = ( <scalar>, <scalar>),

Range:

Limited by surface’s parametric space

Default:

None. Must be specified.

Purpose:

This defines the end of a shared edge for a world-space texture.

Example:

end = (  1.5307337,  5.0       )

light_list

Syntax:

light_list = ( <light>, <light>, … <light> )

Range:

Each light given must have been defined; literals may not be used.

Default:

See below.

Purpose:

Each item referenced must be the name of a previously declared light data item, or an array element of type light (See Light Data Type for more information). Literals may not be used. This lists the lights to be used by this patch. If light_list is omitted or if it is specified and is empty, all nonexclusive lights are used to illuminate the patch. If light_list is specified, and the list contains defined lights, then all instances of those lights in the scene, and only those, will be used for this patch. This enables situations where the user may want 10 lights on a particular object, for example, but only two lights on the rest of the scene.

Comments:

This component may not be animated.

Example:

light_list = ( spot01, spot02, flood, globallight )

mate_curve

Syntax:

mate_curve = ( <name of mate>)

Default:

None. Must be specified if shared_edge is specified.

Purpose:

This specifies the mated curve that the current shared_edge is to be matched up with for world-space texturing.

Example:

mate_curve = trim273932360

mate_patch

Syntax:

mate_patch = ( <name of joined patch>),

Default:

None. Must be specified if shared_edge is specified.

Purpose:

This specifies the mated patch that the current shared_edge is to be matched up with for world-space texturing.

Example:

mate_patch = plane

mate_type

Syntax:

mate_type = <type of surface>,

Default:

None. Must be specified if shared_edge is specified.

Purpose:

This specifies the type of surface that the current shared_edge is to be matched up with for world-space texturing.

Example:

mate_type = TRIM

motion_blur

Syntax:

motion_blur = <scalar>

Default:

ON

Range:

0 (OFF) or non-zero (ON)

Purpose:

If motion_blur_on is set for the file, this flag indicates that motion blur should be calculated for this object.

Example:

motion_blur = ON

motion_blur_shading_samples

Syntax:

motion_blur_shading_samples = <scalar>

Default:

3 - for bump or displacement mapped objects

1 - for all other objects

Range:

>= 3 for bump or displacement mapped objects

> 0 for all other objects

Purpose:

If motion_blur_on is set for the file, this flag indicates the number of samples done for shading of motion-blurred objects.

Example:

motion_blur_shading_samples = 1

motion_blur_texture_sample_level

Syntax:

motion_blur_texture_smaple_level = <scalar>

Default:

3

Range:

0-5

Purpose:

If motion_blur_on is set for the file, this flag indicates the level of sampling done for texturing of motion-blurred objects. A 0 indicates no extra samples (lowest quality) and 5 means highest quality motion-blurred textures.

NoteThis flag does not apply to bump or displacement mapping.

Example:

motion_blur_texture_samples = 3

name

Syntax:

name = ( <name>)

Default:

None. If the mate_type is parametric, a name is not required. Names are required if the mate_type is a trim, due to ambiguities.

Purpose:

This gives a unique name to the shared_edge being world-space textured.

Example:

name = trim273932360

particle_collisions

Syntax:

particle_collisions = BOUNDING_BOX_COLLISIONS | OFF | GEOMETRY_COLLISIONS

Range:

As above

Default:

OFF

Purpose:

To define which objects collide with particles.

Example:

particle_collisions = BOUNDING_BOX_COLLISIONS

opposite

Syntax:

opposite = <scalar>

Range:

0 (FALSE) or not 0 (TRUE)

Default:

FALSE

Purpose:

To reverse the sense of direction of the normal for the patch.

Comments:

This component may be animated. If doublesided is FALSE (for example, for faster execution), opposite can be used to reverse the orientation of the backfacing and frontfacing parts of the patch. This may be done in order to correct potential visibility problems.

Example:

opposite = TRUE

shader

Syntax:

shader = (<shader>)

or

shader = ( <shader>, <shader>, … <shader> )

Range:

The shaders given may be variables or array elements of type shader (see Shader Data Type for more information). Note that there is no such thing as a literal shader.

Default:

None. Must be specified.

Purpose:

This specifies which shading characteristics are assigned to the surface.

Comments:

This component may be animated. If a list of shaders is specified, they will be visible in the order given.

Example:

shader = (pink)

shared_edge

Syntax:

shared_edge = (

(

type <name>,

start = ( <scalar>, <scalar>),

end = ( <scalar>, <scalar>),

name = <name>,

mate_patch = <name>,

mate_type = <curve type>

),

(

type <name>,

start = ( <scalar>, <scalar>),

end = ( <scalar>, <scalar>),

name = <name>,

mate_patch = <name>,

mate_type = <curve type>

),

Default:

None. Must be specified.

Purpose:

This specifies a shared curve or edge between a patch and a trimmed surface, or two patches, or two trimmed surfaces, for use in world-space texturing.

Example:

 shared_edge = (

 type = ULO,

 start = (  0.0      ,  0.0247209 ),

 end   = (  0.0      ,  5.0       ),

 mate_patch = plane,

 mate_curve = trim273932360,

 mate_type = TRIM

),

 type = UHI,

 start = (  1.5307337,  0.0029019 ),

 end   = (  1.5307337,  5.0       ),

 mate_patch = plane2,

 mate_curve = trim273927392,

 mate_type = TRIM

start

Syntax:

start = ( <scalar>, <scalar>),

Range:

Limited by surface’s parametric space

Default:

None. Must be specified if shared_edge is specified.

Purpose:

This defines the start of a shared edge for a world-space texture.

Example:

start = (  1.5307337,  0.0029019 ),

subdivide

Syntax:

subdivide = uniform

or

subdivide = adaptive

Range:

As enumerated above.

Note: You may also use TRUE (adaptive) or FALSE (uniform).

Default:

uniform

Purpose:

This specifies the type of subdivision algorithm to be used.

Comments:

This component may be animated.

NoteThe interpretation of the divisions and curvature components (described elsewhere) depend upon the value given to subdivide.

Example:

subdivide = adaptive

trim_region

Syntax:

trim_region = ( cvs = ( <trim_vertex>, <trim_vertex>, … <trim_vertex> ) )

or

trim_region = ( cvs = ( <trim_vertex>, <trim_vertex>, … <trim_vertex> ),

trim_hole = ( <trim_vertex>,

<trim_vertex>, …

<trim_vertex> ),

trim_hole = ( <trim_vertex>,

<trim_vertex>, …

<trim_vertex> ),

or trim_region = <trim_vertex_variable>

trim_hole = ( <trim_vertex>,

<trim_vertex>, …

<trim_vertex> ) )

or trim_hole = <trim_vertex_variable>

Range:

Any collection of valid trim_vertices (see Trim_vertex Data Type).

Default:

None (no trimming to be done).

Purpose:

Defines a trim region.

Comments:

This component may be animated. There may be an arbitrary number of trim_region components for a patch. The trim_region component uses several sub-components. The CVs sub-component must be specified, but the trim_hole sub-component is optional. The specification of the CVs is identical to previous such specifications, but it must use trim_vertex data items. The trim_hole sub-component is treated separately below.

Example:

trim_region = (

	cvs = (

		trim_vertex (0.0, 1.43192, 1),

		trim_vertex (0.0, 0.0    , 1),

		trim_vertex (1.0, 0.0    , 1),

		trim_vertex (1.0, 2.0    , 1),

		trim_vertex (0.05547, 1.5, 0)

),

trim_hole

Syntax:

trim_hole = ( <trim_vertex>,

<trim_vertex>, … <trim_vertex> )

Range:

Any collection of valid trim_vertices (see Trim_vertex Data Type).

Default:

None (no hole exists).

Purpose:

Defines a hole in a trim region.

Comments:

This component may be animated. There may be an arbitrary number of trim_hole sub-components for a trim_region. The specification of the trim_hole is identical to previous specifications of CVs (except for the fact that its called trim_hole instead). The actual entries must be Trim_vertex Data Type items.

Example:

trim_hole = (

	trim_vertex (0.46123,  1.0, 0),

	trim_vertex (0.5,  0.91163, 0),

	trim_vertex (0.91564,  1.0, 0),

	trim_vertex (0.86419,  1.5, 0)

type

Syntax:

type = ( <name>),

Default:

None. Must be specified if shared_edge is specified.

Purpose:

This provides the type of edge that is being shared by two surfaces for world-space texturing.

Example:

type = TRIM,

uclosed

Syntax:

uclosed = <scalar>

Range:

0 (FALSE) or not 0 (TRUE)

Default:

FALSE (not closed)

Purpose:

Defines whether or not the patch is closed in the u direction.

Comments:

This component may be animated.

Example:

uclosed = 0

uknots

Syntax:

uknots = ( <scalar>, <scalar>, …<scalar> )

Range:

Each entry must evaluate to a real number, which must be greater than or equal to the value of its predecessor.

Default:

None. Must be specified.

Purpose:

This defines the knot vector in the spline’s u direction. It must match with number of CVs given.

Comments:

It may be animated.

Example:

uknots = ( 0, 1, 2, 3, 4, 5 )

vclosed

Syntax:

vclosed = <scalar>

Range:

0 (FALSE) or not 0 (TRUE)

Default:

FALSE (not closed)

Purpose:

Defines whether or not the patch is closed in the v direction.

Comments:

This component may be animated.

Example:

vclosed = 1

vknots

Syntax:

vknots = ( <scalar>, <scalar>, …<scalar> )

Range:

Each entry must evaluate to a real number, which must be greater than or equal to the value of its predecessor.

Default:

None. Must be specified.

Purpose:

This defines the knot vector in the spline’s v direction. It must match with number of CVs given.

Comments:

This component may be animated.

Example:

vknots = ( -6.2, -5, -5, 0, 2.2, 2.2 )

udegree

Syntax:

udegree = <scalar>

Range:

1 to 33

Default:

none

Purpose:

To describe the degree of the nurbs curve in the u direction for patches. To define a syntactically correct curve, there must be at least degree + 1 control vertices.

Comments:

As the degree of the surface increases, it is a good idea to increase the rendering subdivisions for the object defined with that curve.

Example:

degree = 3

vdegree

Syntax:

vdegree = <scalar>

Range:

1 to 33

Default:

none

Purpose:

To describe the degree of the nurbs curve in the v direction for patches. To define a syntactically correct curve, there must be at least degree + 1 control vertices.

Comments:

As the degree of the surface increases, it is a good idea to increase the rendering subdivisions for the object defined with that curve.

Example:

degree = 3