TN-066EN		M3D format for SCOL V4,0
	Category: Tutorials		Sub-Category: 3D Engine
	Created: 2/5/2002		Modification no. and date:

To comply with changes in the OpenGL 3D engine, the format of 3D scene description files (.m3d) has been changed.

A. General

To ensure backward compatibility and take into account the habits of users, 3D scene description files for SCOL will continue to use the M3D extension.

M3D files are text files that can be opened with any text editor. They are easy to understand and are divided into two major sections : declaration of materials and declaration of objects used in the 3D scene.

In an M3D file, the # character indicates that the rest of the line is a comment. Annotations can therefore be added to make the file easier to read.

The new file format is required to describe topologies, color lights and particle management. However, .old. M3D files are still accepted and rendered the way they used to be.

B. Declaring materials

Material blocks use the following format:

material material_name {

color hexa_value

texture texture_path

texturebis texture2_path float_value

facecolor1 hexa_value

facecolor2 hexa_value

type a_flag

type another_flag

}

None of the lines above are indispensable. However, at least one flat color (color field) or one texture file (texture field) must be defined.

Each field included in the material definition is described in detail below:

color hexa_value

The color field specifies a color for flat rendering, which only applies if the material is not textured and does not use any other form of color filling. It is therefore the default color for faces using this material. The color is specified in 6-digit hexadecimal RGB (8 bits R, 8 bits G, 8 bits B). For example, the value for bright red is FF0000.

texture texture_path

The texture field assigns a primary texture to the material. When applying a primary texture, the previously mentioned color is no longer used for filling faces.

texturebis texture2_path float_value

A secondary texture can be declared (multitexturing) in the texturebis field. The secondary texture is blended with the primary texture only if a primary texture has already been declared. The two textures are blended according to an application coefficient between 0 and 1. For instance, 0.52 represents a blending of 48% of the primary texture and 52% of the secondary texture.

The texture is a file path, relative to the Scol Partition, that can be preceded by a filter between % symbols. A filter is a character string that includes a list of procedures :

- C [color - 6 characters] [rate - 2 characters]: color filter (expressed in 24 bits hexa) with a rate between 0 and 255 (2 hexa characters)

- X: Swaps the colors (Red -> Blue -> Green -> Red)

- Y: Swaps the colors (Red -> Green -> Blue -> Red)

- A [color - 6 characters] [distance - 2 characters]: Attractor. All points close to the expressed color are forced to this color. This becomes the transparency color for jpeg textures

- R [rotation - 4 characters] [distance - 2 characters]: Color rotation (HSV model). The angle is between 0 and 65535.

- S [value - 4 characters] [rate - 2 characters]: Saturation filter. The maximum saturation value is specified in 4-byte intervals, between 0 and 65536. The rate is between 0 and 255.

facecolor1 hexa_value

The facecolor1 field indicates the 1st color that will be applied evenly on the faces that use the COLOR1 rendering option (see type section below).

facecolor2 hexa_value

The facecolor2 field indicates the 2nd color that will be applied evenly on the faces that use the COLOR2 rendering option (see type section below). This color is actually used only if multitexture rendering (TEXTURED_BIS rendering option) is applied.

type a_flag

type another_flag

The type field is used to assign rendering options to the material. If no type field is specified, the default flags are used (underlined below). The available flags are :

· FLAT: Not textured; faces are filled with the color specified in "color".

· LIGHT: Faces are lit.

· NOLIGHT: Faces are not lit.

· GOURAUD: Smooth Gouraud light rendering (requires the LIGHT flag).

· TEXTURED: Faces mapped with the primary texture (flag validated if presence of a primary texture is detected)

· TEXTURED_BIS: Faces mapped with the secondary texture (requires the TEXTURED flag)

· COLOR1: the primary texture is filtered with the color specified in the .facecolor1. (if the material is not textured, this is equivalent to a flat color)

· COLOR2: the secondary texture is filtered with the color specified in the .facecolor2. field (requires the TEXTURED_BIS flag : no effect if there is no secondary texture)

· COLOR_VERTEX: the color applied on the faces is based upon the ones indicated for each vertex in the .topo. structure (see below .C. Declaring topologies.). These colors are applied from the vertices, producing a gradation on the faces (vertex color). Requires the COLOR1 flag. If values were specified in the .facecolor1. and .facecolor2. fields, they are discarded.

· TRANSPARENCYnnn: Transparent faces. The keyword TRANSPARENCY is immediately followed (no space) by a coefficient between 0 (opaque) and 255 (transparent).

· ENV : the primary texture is environment mapped (the texture coordinates are automatically generated in order to simulate a reflection effect)

Examples : a multitextured material with a red filter color on texture 1

material logo {

facecolor1 FF0000

texture MyTextures\cube.jpg

texturebis MyTextures\logo.jpg 0.3

type COLOR1

type TEXTURED

type TEXTURED_BIS

}

a multitextured material using color vertex :

material logo2 {

texture MyTextures\cube.jpg

texturebis MyTextures\logo.jpg 0.3

type COLOR1

type COLOR_VERTEX

type TEXTURED

type TEXTURED_BIS

}

C. Declaring topologies

A topology describes the geometry of a 3D object in its own coordinates system. They are written as follows:

topo topology_name {

vertices

polygons

}

A vertex is described by a line with three integer or floating-point x y z coordinates, optionally followed by one or two 24-bit RGB colors (used for the .COLOR_VERTEX. rendering option).

Polygons are described by blocks, composed of :

· one line indicating the name of the material to be applied on subsequent polygons

· a series of polygons. Polygons can be based upon 3 or 4 vertices, and use 0, 1 or 2 textures. A polygon is described using the following format :

vert1_datas vert2_datas vert3_datas [vert4_datas]

where .vertex datas. are a series of 1, 3 or 5 integers :

vertex_index [text1_coord_u text1_coord_v [text2_coord_u text2_coord_v]]

A polygon is therefore described by a series of 3, 4, 9 or 12 integers.

The syntax for topologies is very similar to that for a mesh in the old M3D file format (described in version 3.0 of the SCOL language tutorial).

Example : a multitextured cube with color declaration for some vertices:

topo cube_topo {

# Vertices

100 -100 -100 FFAA08

100 -100 -100 FFA144 FFA142

100 100 -100

100 100 -100 FFFFFF

100 -100 100

100 -100 100 AFB2B2 B2B2B2

100 100 100

# Polygons

logo # Material name

# vert1 vert2 vert3 vert4

0 0 0 0 0 1 255 0 255 0 2 255 255 255 255 3 0 255 0 255

1 0 0 0 0 5 255 0 255 0 6 255 255 255 255 2 0 255 0 255

5 0 0 0 0 4 255 0 255 0 7 255 255 255 255 6 0 255 0 255

4 0 0 0 0 0 255 0 255 0 3 255 255 255 255 7 0 255 0 255

3 0 0 0 0 2 255 0 255 0 6 255 255 255 255 7 0 255 0 255

1 0 0 0 0 0 255 0 255 0 4 255 255 255 255 5 0 255 0 255

}

D. Declaring nodes in the scenegraph

Nodes in the scenegraph are meshes, shells, cameras, collision boxes, lights or sprites. They are nested linearly or recursively and therefore represent the full tree structure of the 3D scene.

For meshes, cameras, lights and shells, a common section that declares the geometric position of the object is found. The data is in the following order:

· three coordinates [x,y,z] that represent the position

· three coordinates [a,b,c] that represent the rotation around Y, X and Z axes (where 6553 stands for 360°)

· a scale coefficient as a percentage (100 for full-size)

· two optional values to define the visibility range

(all these values can be integer or floating-point values)

E. Declaring meshes

There are two types of declarations for mesh blocks : a full declaration (including the topology) or a referenced declaration (referencing an existing topology).

The format of a full declaration is :

mesh mesh_name {

x y z a b c scale rangeMin rangeMax

vertices

polygons

[recursion]

}

The format of the corresponding referenced declaration is :

mesh mesh_name {

x y z a b c scale rangeMin rangeMax

topo topology_name

[recursion]

}

Take the example of a cube positioned at (250,10,20), with a rotation of (32000,0,0) and a scale of 100%, with a visibility range between 50 and 500 in relation to the camera. The full declaration would be :

mesh cube {

250 10 20 32000 0 0 100 50 500

100 -100 -100

100 100 -100

100 -100 100

100 100 100

logo

0 0 0 0 0 1 255 0 255 0 2 255 255 255 255 3 0 255 0 255

1 0 0 0 0 5 255 0 255 0 6 255 255 255 255 2 0 255 0 255

5 0 0 0 0 4 255 0 255 0 7 255 255 255 255 6 0 255 0 255

4 0 0 0 0 0 255 0 255 0 3 255 255 255 255 7 0 255 0 255

3 0 0 0 0 2 255 0 255 0 6 255 255 255 255 7 0 255 0 255

1 0 0 0 0 0 255 0 255 0 4 255 255 255 255 5 0 255 0 255

}

The corresponding referenced declaration would simply be:

mesh cube {

250 10 20 32000 0 0 100 50 500

topo cube_topo

}

The use of the second type of declaration (referenced declaration) is preferred because it allows multiple meshes to share the same topology without having to save it to memory multiple times.

Both forms have similar components. The position of the mesh is specified by the x, y, z coordinates and a, b, c angles (angles between 0 and 65535). The scale parameter is optional. It is expressed as a percentage with 100 representing the normal scale. Double size is 200 and half size is 50, etc.

Additional meshes, cameras, lights or shells can be entered in the [recursion] field.

F. Declaring cameras

Camera blocks are in the following format:

camera camera_name {

x y z a b c scale rangeMin rangeMax

distx disty sx sy

zclip zbrouillard zback

[recursion]

}

The position of the camera is specified by the x, y, z coordinates and a, b, c angles (angles between 0 and 65535). The scale parameter is optional.

The distx and disty parameters specify the distance from the screen at axis x and axis y (used in projection formulas X=distx*x/z and Y=disty*y/z).

G. Declaring shells

The syntax for a shell object is as follows:

shell shell_name {

x y z a b c scale rangeMin rangeMax

[recursion]

}

The position of the shell is specified by the x, y, z coordinates and a, b, c angles (angles between 0 and 65535). The scale parameter is optional.

Additional meshes, cameras, lights or shells can be added after the shell coordinates.

H. Declaring lights

There are two types of lights: white lights (old light model, used in the previous version of the 3D engine, and emulated in the new one to ensure compatibility) and color lights (new feature of the 3D engine).

White lights are defined in the following manner:

light light_name {

x y z a b c scale rangeMin rangeMax

type x [y [d]]

[recursion]

}

Position and rotation parameters are similar to those for other 3D objects in the scene.

The type of light is selected from the following types:

· ambient x: Ambient light. The x parameter (between .64 and +64) is added to the natural lighting of polygons (natural lighting at +31).

· para x y: Directional lighting. The x parameter represents ambient lighting and the y parameter represents actual lighting. Final lighting is between (x-y) and (x+y).

· omni x y d: Point light with fall off. Parameters x and y are the same as for para, and parameter d represents the distance from which light fall off occurs.

· spot x y d: Illuminating point light following a given direction (Z axis by default). The parameters are similar to those for the preceding type.

Color lights are more complex to define. The ambient RGB, diffused RGB and specular RGB components must be defined for the light in 24-bit hexa. Three additional parameters are added to these:

· light diffusion angle: 180° by default, providing omnidirectional lighting. A lower angle is only used for the spot lighting type.

· constant fall-off coefficient: "kc" coefficient in the formula below.

· quadratic fall-off coefficient: "kq" coefficient in the formula below.

Fall-off coefficients are used only for omni and spot types, according to the following formula:

Fall-off factor = 1 / (kc + kq * x²), with x = distance from the light at the lit point.

The declaration is therefore:

colorlight light_name {

x y z a b c scale rangeMin rangeMax

type RGBamb RBGdiff RGBspec spot_angle kc kq

[recursion]

}

I. Declaring particle emitters

Declaring a particle emitter is similar to declaring a shell, but some additional information is required :

emitter emitter_name {

x y z a b c scale

mask flags

life float_value

volume volume_name

vectorA x y z

vectorB x y z

particle particle_name0

effect effect_name0

}

The first fields (up to vectorB) match the parameters of the M3createEmitter function. It is recommended to refer to the Scol Language Reference Manual for a detailed explanation of these values. We describe below the syntactic issues peculiar to the M3D format :

· mask field : the available flags are infinit and additive. To combine both, simply use a white space as a separator.

· volume field : the available identifiers are cone, sphere, plan and line

Particle types and effects are then linked to the emitter. To link multiple types of particles or effects, simply add as many particle or effect lines as required.

Caution : Similar to materials and topologies, particles and effects must be declared before the emitters that reference them (see sections .J. Declaring Particles. and .K. Declaring Effects. below)

J. Declaring particles

The syntax for declaring particles types is as follows (please refer to the M3createParticle function in the Scol Language Manual Reference for a complete description of the semantics of the various parameters) :

particle particle_name {

mask flag

life float_value

rate float_value

weight float_value

size float_value

spin float_value

polarity float_value

topo topology_name

color hexa_value

}

The available flags for the mask field are : billboard, jitter and rainbow. In order to combine these flags, simply add a new .mask. with the desired flag.

The hexadecimal value given for the color field is 32 bit RGBA (2 characters for each component : 0 to 255). The value for 50% transparent red is therefore FF000080.

Caution : the topology referenced in the topo field must have been defined before the particle definition.

The spin, size and color values can be animated throughout the lifespan of each particle. Key values can be fixed for specific dates in the particle lifespan; the value at any given date is then interpolated based upon these key values. The tspin, tsize and/or tcolor fields must be used instead of spin, size and color, to specify key values :

tspin float_value float_value

tsize float_value float_value

tcolor hexa_value float_value

The first parameter is the key value itself, and the second parameter is the .timestamp., given as a floating-point percentage of the particle lifetime.

For instance, for a size of 10 at the particle.s birth, growing to 20 at its mid-life, and then .exploding. up to 200 at its death :

tsize 10.0 0.0

tsize 20.0 50.0

tcolor 200.0 100.0

K. Declaring particle effects

The syntax for declaring effects is as follows :

effect effect_name {

type flag

vectorA x y z

vectorB x y z

vectorC x y z

}

The available identifiers for the type field are : constant, electric, magnetic, helicoid, chaotic0 and chaotic1. The vectorA, vectorB and vectorC fields allow to parameter the chosen effect.

Please refer to the M3createEffect function in the Scol Language Manual Reference for a complete description of the various effects, and the semantics of the vector fields.

This information is provided without charge, for information purposes only, and is not related to any agreement. It is subject to verification by the reader and protected by copyright laws. Unless authorized, duplication, lending and sale are prohibited. All property rights remain with CRYONETWORKS. The company is not responsible for the consequences that result from their use. Copyright © 2000 Cryonetworks.