History:
- v0.02.4
- 2/1/2006 - added general sceneNode support - models, lights, cameras
now share a single class for moving stuff around, added addChild,
getAbsolutePosition(), getAbsoluteTransform(), getScale(), setScale(),
scale(), getPosition(), setPosition(), getRotation(), setRotation(),
remove(), extended lookat()
- v0.02.3
- 1/31/2006 - added setDebugDataVisible() for sceneNodes, getSize(),
getOriginalSize(), getColorFormat() for textures, getVersion(), and
newMaterial()
- v0.02.2
- 1/30/2006 - fixed materials and fogging, both are fully functional,
tweaked demo movie, doc, changed loadMesh to getMesh for consistency's
sake
- v0.02.1
- 1/27/2006 - added lights and fogging, further cleaning of the code
(separation of the main access class from the normal Xtra code)
- v0.02
- 1/26/2006 - material properties can only be read for the time being,
no assigning yet
- v0.01
- 1/25/2006 - first draft
Welcome,
this
is an early preview version of my Irrlicht3d Xtra, a port of the
irrlicht 3d engine
to Director. Please read this document carefully. For any questions,
feel free to contact me at info_at_multimedial.de,
I like to hear from you.
The
Xtra consists of an Irrlicht3d.x32 file, AS WELL as the Irrlicht.DLL.
If either one is missing, then the Xtra will fail to initialize properly.
So both files need to be placed in the Xtras folder.
Also, i want
to set up a Bugzilla server for debugging the Xtra. Since i just
moved into a new office, this will take a couple of weeks before
it will go online. I'll let you know.
General
Notes
So far,
everything (every method and property) has been implemented off the
sprite actor. Please
keep in mind that this is still an alpha version.
All the
media for the 3d world (geometry, textures, etc) is being loaded from
an external media folder, which is supposed
to sit in the searchpath. The easiest thing is to place the media
folder right next to any director movie using the Xtra.
Any object
created returns just a lingo reference name (e.g. "model","texture"),
no name support has been implemented yet, but I got it planned (e.g.
"model("bla")").
Irrlicht3d
specific notes
The Irrlicht3D
engine is different from Shockwave3d in that you need to gain access
to some
master objects before you can actually do anything. A new default irrlicht3d
member in the cast is not exposing any properties, you need a sprite
on the stage for accessing the 3d world.
A newly
created sprite is a completely
empty world, besides the camera scene node which is the view you see
in the sprite and the background color.
The irrlicht
engine works with the concept of a scenegraph. This is why you need
to gain access to the scenemanager object first, before you can do
anything. The SceneManager object allows you to add and remove sceneNodes
to the 3d world. A sceneNode can be anything that can be moved around,
like ...
General
sceneNode support is still rudimentary at this time. There are only
2 methods for sceneNodes currently supported,
getAbsolutePosition(), and setPosition() - see below for their explaination.
Irrlicht
3d Lingo methods and properties
Global
Sprite properties and methods
| Property |
Meaning |
| sprite().fps |
read only -
Frames per second, as reported by the engine |
| sprite().antialias |
bool - set and
read, toggles antialiasing on and off |
| sprite().bits |
should be
colordepth (16,32 bits), doesn't work in windowed mode
|
| sprite().drivertype |
read/write
- symbol
reports and
sets the videodriver used. Possible values are
- #NULL
- null driver (no image)
- #software
- software renderer (optimized for speed, quirky image due
to missing triangle clipping support for the time being)
- #software2
- optimized software renderer by another author
- #Direct3d8
(default)
- #direct3d9
- #openGl
(doesn't seem to work?)
|
| sprite().stencilbuffer |
boolean -
read/write
sets if the
3d scene is to support a stencilbuffer for drawing shadows
|
| sprite().vsync |
bool, r/w
waits for
the vertical sync signal for redrawing image, is not supposed
to work in windowed mode, so it is pretty uch useless
|
| sprite().bgColor |
color object,
r/w
allows to
read and set the background color of the 3d world - takes an
rgb() lingo value (e.g. sprite(1).bgColor=rgb(220,200,180))
|
| sprite().primitiveCount |
returns the
number of polys currently being drawn by the engine |
| Methods |
Meaning |
| sprite().getSceneManager() |
read only
gets a reference
to the SceneManager of the IrrlichtEngine.
Needed to
load stuff like models.
|
| sprite().getVideoDriver() |
read only
gets a reference
to the current VideoDriver of the irrlicht engine. Needed for
loading textures for instance.
|
| sprite().addZipFileArchive(filename) |
write only
adds a specified
ZIP/Pk3 file to the list of readable files, meaning that after
adding the archive, you can load files being in the archive
- beware of internal folders inside archives
Example:
sprite(1).addZipFileArchive("media/MyArchive.zip")
mdl=sprite(1).getSceneManager().loadMesh("models/myModel.bsp")
Loads
the file myModel.bsp, situated in the folder models of the
archive "MyArchive.zip"
|
| sprite().clear() |
clears the 3d
world (crashes for the time being, i dunno why, probably because
of a missing graphics object) |
| sprite().getVersion() |
string
returns the
build number of the irrlicht engine
|
SceneManager
SceneManager
Methods
(acquire
by doing something like smgr=sprite(1).getSceneManager())
|
Meaning |
| smgr.getMesh(filename) |
returns
a reference to the newly created sceneNode
loads the
mesh filename into the 3d world and automatically creates a
sceneNode for it
Example:
put
smgr.getMesh("media/faerie.md2")
-- sceneNode(d8f87c)
No control
over the meshes just yet other than just moving them around.
Supported
mesh types are the ones supported by the engine:
- oct
file for Paul Nette's FSRad or from Murphy McCauley's Blender
.oct exporter. The oct file format contains 3D geometry
and lightmaps and can be loaded directly by Irrlicht
- Quake
2 MD2 model
- Milkshape 3d
skeletal animation
- Maya .obj
not animated
- Quake
3 .bsp Map, not animated.
- 3D
Studio .3ds file
- Microsoft
Direct3D .x-file. Can contain static and skeletal
animated skinned meshes. This is the standard and best
supported format of the Irrlicht Engine.
- My3D Mesh,
the file format by Zhuck Dimitry.
- Pulsar
LMTools (.lmts) file
- Cartography
Shop .csm file
|
| smgr.getCamera() |
returns
a reference to the current camera |
| smgr.newLight() |
returns a light
reference |
VideoDriver
VideoDriver
Methods
acquire
by doing something like vmgr=sprite(1).getVideoDriver()
|
Meaning |
| vmgr.getTexture(filename) |
returns
a reference to the newly created texture object
loads the
texture into the 3d world and automatically creates a texture
object for it
Example:
put
vmgr.getTexture("media/faerie2.bmp")
-- IrrlichtTexture
|
| vmgr.setFog(color,linearfog,
start, end, density, pixelfog, rangefog) |
returns
nothing
color is
a lingo color object (e.g. rgb(1,2,3))
linearfog is a boolean - if off, exponentail fog is used and some props
won't apply
start, end are floats (in worldunits)
density is a float
pixelfog is boolean
rangefog is boolean
sets the
videodriver to show fog
Example:
sprite(1).getVideoDriver().setFog(rgb(32,64,128),1,50,100,0.01,0,0)
|
| vmgr.newMaterial() |
returns a
material ref to a new material
NOTE: this
was supposed to help make new materials (=shaders). Turns out
one can apparently not set the complete material of a sceneNode?
The material cannot be removed from a sceneNode, meaning that
a material always has a specific shader associated with it
This will
either be dropped, or will need more infrastructure in order
to make materials swappable
|
General SceneNode
Methods
(sceneNodes
are Models, Lights, Camera references)
SceneNode
Methods
|
Meaning |
| node.getAbsolutePosition() |
returns
a 3d vector of the absolute position of the node in the 3d
world
no scripted
parent-child support yet, except for loaded models
returns a
3d vector with the current position of the sceneNode
|
| node.setDebugDataVisible(boolean) |
sets DebugData
(=a bounding box) for the sceneNode (0=off, 1 = on) |
| node.addChild(noderef) |
makes the node passed a child object to the specified node:
mdl.addChild(cam) -- links the cam to the model |
| node.getAbsoluteTransform() |
returns the absolute transform of the selected node |
| node.getScale() |
returns a vector with the current scaling of the node
|
node.setScale(vector)
node.setScale(float tripel)
node.setScale(float) |
sets the scaling of the specified node to the value(s) passed (either
vector or float tripel or single float) |
| node.getPosition() |
returns a vector with the current position of the node
NOTE: absolute
or relative to parent? |
node.setPosition(vector)
node.setPosition(float tripel) |
sets the position of the node to the specified values
NOTE: absolute
or relative to parent? |
| node.getRotation() |
returns a vector with the current rotation of the node
NOTE: absolute
or relative to parent? |
node.setRotation(vector)
node.setRoation(float tripel) |
sets the rotation of the current node to the value(s) specified
NOTE: absolute or relative to parent? |
| node.remove() |
removes the node from the world (=deletes it, it cannot be readded!)
dangling references to the model are VOID and crash Director for
the time being |
Models
SceneNode
Methods
|
Meaning |
| node.setMaterialTexture(texturelayer, texturereference) |
sets
the texturelayer of the node's material to the texture supplied
- possible texturelayer values are 0 or 1 -
just
2 layers available
|
| node.getMaterialCount() |
returns
the amount of materials associated with this sceneNode. Return
value is usually 1, meaning that there is just one material on
the model |
| node.getMaterial(index) |
index
is the index to the material of the node
returns
a reference to a material (=analog to shader in Shockwave3)
index
must be <= node.getMaterialCount() for this access to work
|
Materials
Material
Properties
Materials
are the same as shaders in Shockwave3d - you get them by asking
a sceneNode for its material, e.g.
sceneNode.getMaterial(1)
This gets
the first material from the sceneNode. Note that the index
is NOT zero based, asking for getMaterial(0) won't get you
nothing.
|
Meaning
|
| material.AmbientColor |
r/w
returns
a color object with the ambient Color of the material
|
| material.DiffuseColor |
r/w
returns
a color object with the diffuse Color of the material
|
| material.EmissiveColor |
r/w
returns
a color object with the emissive Color of the material
|
| material.shininess |
r/w
returns a
float value with the shininess of the material (range?)
|
| material.SpecularColor |
r/w
returns
a color object with the specular Color of the material
|
| material.AnisotropicFiltering |
r/w
returns boolean
value for AnisotropicFilterin, default is false.
|
| material.BackfaceCulling |
r/w
returns boolean
value for Backface Culling, default is true
|
| material.BilinearFilter |
r/w
returns boolean
value for Bilinear Filtering, default is true
|
| material.flags |
not implemented
yet, is supposed to return array of flags for material |
| material.FogEnable |
r/w
returns boolean
value if material should be affected by fogging
|
| material.GoureaudShading |
r/w
returns boolean
value if material should be Goureaud Shaded
|
| material.Lighting |
r/w
returns boolean
value if material should be lighted or not
|
| material.normalizeNormals |
r/w
returns boolean
value if normals should be normalized
|
| material.texture1 |
r/w
returns texture
reference for first texture of material
|
| material.texture2 |
r/w
returns texture
reference for second texture of material
|
| material.texturelist |
not implemented
yet, will give access to lingo list with textures of material |
| material.trilinearFilter |
r/w
boolean value
if material should be trilinear filtered - defaults to false
|
| material.wireframe |
r/w
boolean value
if material should be rendered in wireframe mode, default is
false
|
| material.ZBuffer |
r/w
boolean value
if material should write to ZBuffer or not, default: true
|
| material.ZWriteEnable |
r/w
boolean if
material may be written to ZBuffer or if it is readOnly, default
true
|
Textures
Texture
methods.
Textures are
returned from materials and can be loaded |
Meaning
|
| txtr.getSize() |
returns a
lingo rect with the current size of the texture, as eventually
arranged by the driver (usually a power of 2)
|
| txtr.getOriginalSize() |
returns a lingo
rect with the original size of the texture at import time |
| txtr.getColorFormat() |
returns a
lingo symbol of the color format of the texture - possible values
are:
#rgba8888
= 32 bit color
#rgba5651 = 16 bit color (5 bits red, 6 bits green, 5 bits blue, 1 bit
alpha)
#rgba8880 = 24 bit color (normal RGB, no alpha)
|
Cameras
Camera
Node Methods
|
Meaning |
| cam.getAbsolutePosition() |
returns
a 3d vector of the absolute position of the node in the 3d
world
no scripted
parent-child support yet, except for loaded models
returns a
3d vector with the current position of the sceneNode
|
| cam.setPosition(x,y,z) |
sets the
position of the node
NOTE: the
x, y, z are passed as single values, not as a vector! This
is not implemented yet, although it will be in future versions
|
cam.lookat(x,y,z)
cam.lookat(noderef) |
points
the camera at x,y,z or the noderef passed (e.g. in order to point
a camera to the model) |
Lights
Light
Properties
|
Meaning |
| light.AmbientColor |
r/w
a color
object describing the ambient lighting emitted by the light
|
| light.DiffuseColor |
r/w
a color
object describing the diffuse lighting emitted by the light
(this is the main light color)
|
| light.castShadow |
bool, r/w
makes the
light cast a shadow IF the device has been set to have a stencilbuffer
(initParams on the device)
NOTE: for
testing purposes, the stencilbuffer has been set to always
be ON in the builds
|
| light.position |
vector, r/w
position
of the light as a vector
if light.type=#directional,
then this is the direction vector the light is coming from
|
| light.radius |
float, r/w
radius of
light, everything within the radius of the light will be lighted
|
| light.specularColor |
r/w
a color
object describing the color of the specular hightlights caused
by the light
|
| light.type |
r/w
symbol, can
either be #point or #directional
|
See the demo movie
for more details. I could need some help with this, especially for
the docs. So if anyone feels inclined, please let me know and i will
send you the source in order for you to read the implemented methods
and properties.
Have fun!
|
