Scene Files

LightWave

EA IFF 85 Object Files File Formats Table of Contents

Scene Files

November 9, 2001

This document describes the LWSC version 3 file format for 3D scenes used by LightWave 6.0 and later. At this point, it's an incomplete rough draft that's missing descriptions of most of the keywords. But the introductory information will allow you to parse the file at least, and the semantics of most of the keywords can be deduced.

If you've worked with version 1 of the format (version 2 was an unreleased interim format), version 3 will seem quite familiar. Scene files are still text files containing keyword-value pairs. The most important difference is in the way keyframe data is stored, but obviously there are many others comprising features not available in LightWave prior to 6.0.

Item Numbers

When a scene file needs to refer to specific items to establish item relationships (parenting, for example), it uses item numbers. Items are numbered in the order in which they appear in the file, starting with 0.

Item numbers can be written in one of two ways, depending on which keyword they're used with. In general, if the type of the item (object, bone, light, camera) can be determined from the keyword alone, the item number will simply be the ordinal, written as a decimal integer. When the keyword can be used with items of more than one type, the item number is an unsigned integer written as an 8-digit hexadecimal string, the format produced by the C-language "%8X" print format specifier, and the high bits identify the item type.

The first hex digit (most significant 4 bits) of the hex item number string identifies the item type.

1 - Object
2 - Light
3 - Camera
4 - Bone

The other digits make up the item number, except in the case of bones. For bones, the next 3 digits (bits 16-27) are the bone number and the last 4 digits (bits 0-15) are the object number for the object the bone belongs to. Some examples:

10000000 - the first object
20000000 - the first light
4024000A - the 37th bone (24 hex) in the 11th object (0A hex)

Blocks

Information in a scene file is organized into blocks, the ASCII text analog of the chunks described in the IFF specification. Each block consists of an identifier or name followed by some data. The format of the data is determined by the block name. Block names resemble C-style identifiers. In particular, they never contain spaces or other non-alphanumeric characters.

A single-line block is delimited by the newline that terminates the line. Multiline blocks are delimited by curly braces (the { and } characters, ASCII codes 123 and 125). The name of a multiline block follows the opening curly brace on the same line. The curly brace and the name are separated by a single space. The data follows on one or more subsequent lines. Each line of data is indented using two spaces. The closing brace is on a line by itself and is not indented.

Individual data elements are separated from each other by a single space. String data elements are enclosed in double quotes and may contain spaces.

Blocks can be nested. In other words, the data of a block can include other blocks. A block that contains nested blocks is always a multiline block. At each nesting level, the indention of the data is incremented by two additional spaces.

   SingleLineBlock data
   { MultiLineBlock
     data
     { NestedMultiLineBlock
       data
     }
   }

Envelopes

An envelope defines a function of time. For any animation time, an envelope's parameters can be combined to generate a value at that time. Envelopes are used to store position coordinates, rotation angles, scale factors, camera zoom, light intensity, texture parameters, and anything else that can vary over time.

The envelope function is a piecewise polynomial curve. The function is tabulated at specific points, called keys. The curve segment between two adjacent keys is called a span, and values on the span are calculated by interpolating between the keys. The interpolation can be linear, cubic, or stepped, and it can be different for each span. The value of the function before the first key and after the last key is calculated by extrapolation.

In scene files, an envelope is stored in a block named Envelope that contains one or more nested Key blocks and one Behaviors block.

   { Envelope
     nkeys
     Key value time spantype p1 p2 p3 p4 p5 p6
     Key ...
     Behaviors pre post
   }

The nkeys value is an integer, the number of Key blocks in the envelope. Envelopes must contain at least one Key block. The contents of a Key block are as follows.

value
The key value, a floating-point number. The units and limits of the value depend on what parameter the envelope represents.

time
The time in seconds, a float. This can be negative, zero or positive. Keys are listed in the envelope in increasing time order.

spantype
The curve type, an integer. This determines the kind of interpolation that will be performed on the span between this key and the previous key, and also indicates what interpolation parameters are stored for the key.
0 - TCB (Kochanek-Bartels)
1 - Hermite
2 - 1D Bezier (obsolete, equivalent to Hermite)
3 - Linear
4 - Stepped
5 - 2D Bezier
p1...p6
Curve parameters. The data depends on the span type.
TCB, Hermite, 1D Bezier
The first three parameters are tension, continuity and bias. The fourth and fifth parameters are the incoming and outgoing tangents. The sixth parameter is ignored and should be 0. Use the first three to evaluate TCB spans, and the other two to evaluate Hermite spans.
2D Bezier
The first two parameters are the incoming time and value, and the second two are the outgoing time and value.

The Behaviors block contains two integers.

pre, post
Pre- and post-behaviors. These determine how the envelope is extrapolated at times before the first key and after the last one.
0 - Reset
Sets the value to 0.0.
1 - Constant
Sets the value to the value at the nearest key.
2 - Repeat
Repeats the interval between the first and last keys (the primary interval).
3 - Oscillate
Like Repeat, but alternating copies of the primary interval are time-reversed.
4 - Offset Repeat
Like Repeat, but offset by the difference between the values of the first and last keys.
5 - Linear
Linearly extrapolates the value based on the tangent at the nearest key.

The source code in the sample/envelope directory of the LightWave plug-in SDK demonstrates how envelopes are evaluated.

Scene

FirstFrame nfirst
LastFrame nlast
FrameStep nstep
The frame range and step size for rendering. In the simplest case, the first frame and frame step are 1, and the last frame is the number of frames to be rendered.

PreviewFirstFrame nfirst
PreviewLastFrame nlast
PreviewFrameStep nstep
The frame range and step size for previewing. These may be unrelated to the values for rendering. They also control the visible ranges of certain interface elements, for example the frame slider in the main window.

CurrentFrame nframe
The frame displayed in the interface when the scene is loaded.

FramesPerSecond gframes
This controls the duration of each frame.

Objects

LoadObjectLayer nlayer sfilename
Begins a group of statements about an object. The layer number is the index recorded in the LAYR chunk of the object file.

ShowObject nvisibility ncolor
Determines how the object is displayed in the interface. The visibility codes are
0 - hidden
1 - bounding box
2 - vertices only
3 - wireframe
4 - front face wireframe
5 - shaded solid
6 - textured shaded solid

The color used to draw bounding boxes, vertices and wireframes can be one of the following.

0 1 2 3 4 5 6 7 8 9 10 11 12 13 14

The default visibility and color are stored in the config file. If they haven't been altered by the user, they are textured shaded solid (6) and cyan (3) in LightWave 6.5.

ObjectMotion
NumChannels nchannels
Channel nindex
{ Envelope ...
The ObjectMotion keyword signals the start of the motion information for the object. Motions are stored in envelopes, one for each motion channel. There are 9 standard channels, numbered from 0 to 8.

0, 1, 2 - (x, y, z) position
3, 4, 5 - (heading, pitch, bank) rotation
6, 7, 8 - (sx, sy, sz) scale factors along each axis

The values of all of these are relative to the object's parent, if it has one.

UseBonesFrom 1
.

Plugin sclass nlistpos sname
EndPlugin
Lists an object plug-in. The class can be

MorphAmount
MorphTarget
MorphSurfaces
MTSEMorphing
.

DisplacementMaps
{ TextureBlock ...
.

ClipMaps
{ TextureBlock ...
.

ObjectDissolve
.

DistanceDissolve
.

MaxDissolveDistance
.

AffectedByFog
.

UnseenByRays
.

UnseenByCamera
.

ShadowOptions
.

ExcludeLight
.

PolygonEdgeFlags
.

PolygonEdgeThickness
.

PolygonEdgeColor
.

PolygonEdgesZScale
.

EdgeNominalDistance
.