Scene File Format

From Digital Spaces

The .scene file format is used as the simplest way of populating the 3D scene. A very simple .scene file may look like this:

<scene>
  <environment>
    <colourAmbient r="0.5" g="0.5" b="0.5" />
  </environment>
  <nodes>
    <node>
      <entity meshFile="sample.mesh" />
    </node>
  </nodes>
</scene>
 

This sets the world ambient lighting to RGB(0.5,0.5,0.5), which is a dim grey. It also loads the sample.mesh model at the default co-ordinates of (0,0,0). Below is reference for each of the possible entries in the .scene file format. This document may be incomplete, due to the way the SGManager is implementated, actual capabilites available are dependant on the rendering module.

Contents 1 Common Structures 1.1 Colour 1.2 Vector 1.3 Quaternion 2 environment section 2.1 colourAmbient 2.2 colourBackground 2.3 fog 2.4 shadows 2.5 skyBox 2.6 skyDome 2.7 skyPlane 2.8 title 2.9 gravity 2.10 extents 2.11 physicsGroup 2.11.1 collide 2.11.2 dontCollide 2.12 renderTexture 2.13 perRenderGroup 3 externals 4 nodes 4.1 node 4.1.1 position 4.1.2 scale 4.1.3 orientation/rotation 4.2 entity 4.3 light 4.3.1 lightAttenuation 4.3.2 lightRange 4.4 camera 4.4.1 clipping 4.4.2 renderTarget 4.5 billboardSet 4.5.1 billboard 4.6 particleSystem 4.7 shape 4.7.1 size 4.7.2 radius 4.7.3 length 4.7.4 distance 4.7.5 normal 4.8 joint 4.8.1 axis 4.8.2 axis2 4.8.3 limit 4.8.4 settings 4.8.4.1 float 4.8.4.2 vector

Common Structures

There are certain common substructures used throughout the .scene format.

Colour

A tag with "r", "g", "b" and optionally "a" attributes. These are floating point values between 0.0 and 1.0.

Vector

A tag with "x", "y", "z" attribues. These are floating point numbers with no range limits.

Quaternion

A tag with either:

• "w", "x", "y", "z"
• "qw", "qx", "qy", "qz"
• "axisx", "axisy", "axisz"
• "anglex", "angley", "anglez", "angle"

These tag represents an orientation. The w,x,y,z and qw,qx,qy,qz formats are directly the quaternion values. axisx,axisy,axisz are Euler angles, around each of the axis respectively. These angles are specified in radians. anglex,angley,anglez,angle are rotation around an axis. The angle is specified in radians.

environment section

This is passed to all modules that implement DISGRepresentative, via DIAcceptConfiguration1::ParseConfiguration.

colourAmbient

3DVisuals_OGRE: Sets the scenes ambient lighting. Defaults to black. Structure: Colour

colourBackground

3DVisuals_OGRE: Does nothing, should set the clearing colour of the viewport. Structure: Colour

fog

3DVisuals_OGRE: Sets the fog mode used. Defaults to mode=none

• mode: exp, exp2, linear
• expDensity: float
• linearStart: float
• linearEnd: float
• colourDiffuse: Colour

See [OGRE API], specifically setFog

shadows

3DVisuals_OGRE: Sets the type of shadow rendering

• type: texture
  • fadeStart: float
  • fadeEnd: float
  • textureSize: int
  • textureCount: int
  • To be added:
    • Texture Self Shadow
• type: stencil/stencil1/stencil modulative, stencil2/stencil additive
• diffuseColour: colour. Defaults to ambientColour with alpha of 0.9
• To be added:
  • Shadow Far Distance

See [OGRE API], specifically setShadowTechnique and setShadowTexture*

skyBox

3DVisuals_OGRE

• material: string
• distance: float
• drawFirst: bool
• orientation/rotation: Quaternion

See [OGRE API], specifically setSkyBox

skyDome

3DVisuals_OGRE

• material: string
• curvature: float
• tiling: float
• drawFirst: bool
• orientation/rotation: quaternion

See [OGRE API], specifically setSkyDome

skyPlane

3DVisuals_OGRE

• material: string
• planeX, planyY, planeZ, planeD: float
• scale: foat
• tiling: float
• bow: float
• drawFirst: bool

See [OGRE API], specifically setSkyPlane

title

Physics_ODE. Contains text that is used for the name of the PhysicsWorld.

gravity

Physics_ODE. type: Vector

extents

Physics_ODE. Currently does nothing, may in future be used as an optimization. type: Vector

physicsGroup

Physics_ODE. Used to control if collisions happen between groups, or within the same group. Default is collisions happen between groups, and not within group.

• id: integer. Identifier for group, as used in the shape group property.
• collideSelf: bool. Set if the group should perform collision internally.

collide

Sets that the physics group specified in physicsGroup should collide with the group specified here.

• id: integer: Identifier for group, as used in the shape group property.

dontCollide

Sets that the physics group specified in physicsGroup should not collide with the group specified here.

• id: integer: Identifier for group, as used in the shape group property.

renderTexture

• name: string. Name of the renderTexture created, and is how it is refferred to by camera's later.
• width: int. Dimension of the texture, in pixels. Note that this is a minimum, the implementation may extend this for optimization.
• height: int. Dimension of the texture, in pixels. Note that this is a minimum, the implementation may extend this for optimization.
• autoUpdate: bool. Defines if the texture should be automatically updated at the same time as the main window. Defaults to true.
  • To manually update, see DIOGRETextureManager::UpdateRenderTarget

I suggest using powers of 2 (128, 256, 512, 1024) and keep in mind this resource is created on the video card, so may depend on the render system being used. See RenderToTexture for an example.

perRenderGroup

• lighting: bool. Sets if lights should only affect entities with the same renderGroup property.

externals

The SGManager ignores this entry, but it is in the original .scene specification (as developed for OGRE). Possibly future development will see it being parsed by the Resource Manager.

nodes

This is the part that builds the scenegraph heirachy.

• name: string. Signifies where on the existing heirachy the child nodes should be attached. Default is "ROOT", which is an automatically created SGNode.
• parent: string. Same function as name, but more accurately describes its purpose.

node

Nodes are the nestled heirachal objects all render objects are attached to.

• name: string. If not present, a garenteed unique name is generated.
• To be added:
• body: bool. If true, a physics body representation will be created
• ignoreGravity: bool: If true, the physics body will ignore gravity
• mass: child tag
  • Vector: Sets the inertia_tensor
  • value: float: Sets the mass.
• damping: child tag: Sets the amount per tick that the bodies motion will be scaled back. Used to simulate continuous resistance, such as air.
  • linear: float
  • angular: float

position

SGManager: Position relative to the parent node. type: Vector

scale

SGManager: Scale, relative to the parent node. type: Vector.

orientation/rotation

SGManager: Orientation, relative to the parent node. type: Quaternion

entity

3DVisuals_OGRE: Creates an entity from a meshfile.

• name: string. If not present, a garenteed unique name is generated.
• meshFile: string. Needed by 3DVisuals_OGRE to create the entity.
• castShadows: bool.
• renderGroup: int. Specifies which renderGroup the object should be rendered in. Related to Lights renderGroup and environment's perRenderGroup options. Default: 0. Valid values range from -4 to 4.

NOTE: Future versions of 3DVisuals_OGRE may alter this behaviour, as OGRE has altered how render groups work.

• To be added:
  • static: bool. Optimizes rendering, but may affect scenegraph. In OGRE, static batching duplicates original entity, which should be destroyed.

light

3DVisuals_OGRE: Creates a light

• name: string. If not present, a garenteed unique name is generated.
• visible: bool
• castShadows: bool
• colourDiffuse: Colour
• colourSpecular: Colour
• type: default "point", may be "directional" or "spot"
  • May support targetDirectional and targetSpot in future
• normal: Vector. Sets the direction the light is pointing.
• position: Vector. This is an offset from the SGNode it's attached to. It's not recommended, set the position of the parent, or if the parent is shared, give the light its own child node.
• renderGroup: int. Specifies which renderGroup's objects this light should affect. Related to Entities renderGroup and environment's perRenderGroup options. Default: 0. Valid values range from -4 to 4.

NOTE: Future versions of 3DVisuals_OGRE may alter this behaviour, as OGRE has altered how render groups work.

lightAttenuation

Only applicable to point lights.

• range: float
• constant: float
• linear: float
• quadratic: float

Reasonable defaults are: constant=0.0, linear=1.0, quadratic=0.0 . This will cause the light brightness to fade smoothly across the range specified.

lightRange

Only applicable to spotlights.

• inner: float
• outer: float
• falloff: float

camera

• name: string. If not present, a garenteed unique name is generated.
• fov: float
• aspectRatio: float
• projectionType. Default of "perspective", may be "orthographic"
• normal: Vector.
• position: Vector. This is an offset from the SGNode it's attached to. It's not recommended, set the position of the parent, or if the parent is shared, give the light its own child node.

clipping

• near: float
• far: float

renderTarget

• name: string. This is the same name as specified in the <enviroment><renderTexture /> entry.
  • Note: In future this will allow rendering to non-texture targets, such as the main window. This is why the element is renderTarget, not just renderTexture.
• left: float. Ranges from 0.0 to 1.0, specifies where on the target texture the camera will render. Defaults to 0.
• top: float. Ranges from 0.0 to 1.0, specifies where on the target texture the camera will render. Defaults to 0.
• width: float. Ranges from 0.0 to 1.0, specifies where on the target texture the camera will render. Defaults to 1.
• height: float. Ranges from 0.0 to 1.0, specifies where on the target texture the camera will render. Defaults to 1.
• zOrder: int. Specifies the order this camera is rendered onto the renderTexture. Must be unique for the texture, if multiple camera's are added with the same zOrder, adding will fail. Defaults to 0.
• gui: bool. Specifies if the GUI should be rendered on this camera. Defaults to false.

See RenderToTexture for an example.

billboardSet

• name: string. If not present, a garenteed unique name is generated.
• type: string. Defaults to "point", options are "orientedCommon" and "orientedSelf".
• center: string. Defaults to "center". Options are "topLeft", "topCenter", "topRight", "centerLeft", "centerRight", "bottomLeft", "bottomCenter", "bottomRight".
• width: float.
• height: float.
• commonDirection: Vector.

billboard

• position: Vector

To be added:

• colourDiffuse: Color
• width: float
• height: float
• orientation/rotation: quaternion

particleSystem

• file: string. Name of Ogre particle definition script (.particle).
• template: string. Alternate for file.

shape

Physics_ODE. Creates a Physics shape. In the old ScenegraphManager shape elements had to be children of entity elements. In the newer SGManager implementation, they should be children of node elements. However there is compatibility code that searches for shape elements as children of entity elements, and processes them as if they were children of the entity elements parent node element.

• type: string. Possible values are:
  • box
  • sphere
  • cylinder
  • plane
  • capsule
  • mesh
  • boundingbox
  • boundingsphere
• group: integer in range from 0 to 255. Is used internally to ODE for testing potential collisions.

NOTE: By default, shapes of the same group do not collide with each other, while objects of different groups do.

• entity: string. Name of the entity to be used when constructing the shape data. Applicable to mesh, boundingbox and boundingsphere.

These properties are handled by the SGManager

• position: child element: Vector
• orientation: child element: Quaternion

size

Vector. Used by Box shape

radius

• value: float

Used by sphere, capsule, cylinder shapes.

length

• value: float

Used by capsule, cylinder shapes.

distance

• value: float

Used by plane shape.

normal

Vector. Used by plane shape.

joint

Physics_ODE.

• type: string. Supported values:
  • ball
  • hinge
  • hinge2
  • slider
• body: string. Name of a node defined with body="true".
• otherBody: string. Name of a node defined with body="true".

For both body and otherBody, if the specified name is not a valid node (or is empty), the joint will be fixed to the "world", making it immobile.

axis

Physics_ODE. Vector. Used by types: hinge, hinge2, slider.

axis2

Physics_ODE: Vector. Used by type: hinge2

limit

Physics_ODE. Sets either the angular or the linear limit of a joint. Multiple limit elements may be specified, however if they are both of the same type, the last applied will be the one used.

• type: string. Values: angular, linear.

Linear is only applicable to slider joints. angular is only applicable to hinge and hinge2 joints.

• low: float. In the case of linear, is distance in meters. In the case of angular, is the angle in radians, and should be between -PI and PI.
• high: float: In the case of linear, is distance in meters. In the case of angular, is the angle in radians, and should be between -PI and PI.

If low is not less then high, then no limits will be applied at all. Also note that setting both high and low to zero may not cause the expected "locked together" effect. Using low values (-0.0001 and 0.0001) seem more reliable.

• axis: unsigned char: Specifies which axis of multi-axis joints this limit should be applied to. In all available implementations (Physics_ODE) this parameter is ignored.

Parameters handled by SGManager:

• position
• orientation/rotation: This is currently ignored in the available implementations (Physics_ODE).

settings

A free form method of setting properties by name and type.

<joint ...>
  <settings>
    <setting name="stopERP">
        <float val="0.7" />
    </setting>
  </settings>
</joint>
 

The code used to parse the settings element supports many data types, but the available physics implementation (Physics_ODE) ignores all but float and vector. (It should also handle bool? This is a bug?) For a description of these settings, see [ODE Joints], particularly [ODE Joint Parameters].

float

• stopERP: hinge, slider, hinge2
• stopCFM: hinge, slider, hinge2
• CFM: hinge, slider, hinge2
• bounce: hinge, slider, hinge2
• fudge: slider
• suspensionERP: hinge2
• suspensionCFM: hinge2

These properties are extensions from ODE, and are used to fake springed suspension on a slider joint. Mtor force is set based on the sliders distance between its linear limits.

• springSpeed
• springMinForce
• springMaxForce

vector

These properties should be set through the appropriate elements, rather then through the settings map. Support for these may be removed.

• position
• axis
• axis2