DX Studio Help - welcome to deby.net

Transcription

DX Studio
User Guide and Reference Guide
by Worldweaver Ltd.
This is a PDF version of the DX Studio help file that is
suitable for printing.
For online help, please visit http://www.dxstudio.com/help/
or for interactive help hit F1 while using DX Studio.
I
DX Studio™ Help
Table of Contents
Foreword
0
Part I Welcome to DX Studio™
1
Part II Getting Started
2
1 Installation...................................................................................................................................
2
2 Exploring ...................................................................................................................................
the Software
4
3 DX Studio ...................................................................................................................................
Documents
6
7
Part III Tutorials
1 Introduction
...................................................................................................................................
7
2 Other Tutorials
...................................................................................................................................
8
Building a Porfolio Application
.......................................................................................................................................................... 9
Import and Export .......................................................................................................................................................... 21
Models from 3D.........................................................................................................................................................
Studio Max
21
Importing Other.........................................................................................................................................................
File Formats
23
Scripting
.......................................................................................................................................................... 24
Hello World
......................................................................................................................................................... 24
Events
......................................................................................................................................................... 25
Variables
......................................................................................................................................................... 26
Functions
Networking
......................................................................................................................................................... 27
.......................................................................................................................................................... 28
Simple Networking
......................................................................................................................................................... 28
30
Part IV DX Studio™ Editor
1 Introduction
...................................................................................................................................
30
2 User Guide
...................................................................................................................................
30
Director Level Concepts
.......................................................................................................................................................... 31
Introduction
......................................................................................................................................................... 31
Using Scenes ......................................................................................................................................................... 32
Using Layers ......................................................................................................................................................... 33
Using Resources
......................................................................................................................................................... 34
Building 2D Scenes.......................................................................................................................................................... 35
Introduction
......................................................................................................................................................... 35
Editor Overview......................................................................................................................................................... 35
Building 3D Scenes.......................................................................................................................................................... 36
Introduction
......................................................................................................................................................... 36
Editor Overview......................................................................................................................................................... 36
Creating Shapes
......................................................................................................................................................... 37
Creating Terrain......................................................................................................................................................... 38
Modifying Shapes
......................................................................................................................................................... 40
Editing Subgroups
......................................................................................................................................................... 41
Materials
......................................................................................................................................................... 41
Introduction
Particles
......................................................................................................................................... 41
......................................................................................................................................................... 42
Introduction
......................................................................................................................................... 42
© 2003-2005 Worldweaver Ltd.
Contents
II
Level of Detail (LOD)
......................................................................................................................................................... 43
Introduction
......................................................................................................................................... 43
Using LOD for collision
.........................................................................................................................................
and shadows
44
Environments ......................................................................................................................................................... 44
Introduction
......................................................................................................................................... 44
Creating Environments
.........................................................................................................................................
with Terragen
45
Output Formats
.......................................................................................................................................................... 46
Introduction
......................................................................................................................................................... 46
Building an EXE......................................................................................................................................................... 46
Building for the .........................................................................................................................................................
Web
47
Building Movies......................................................................................................................................................... 48
Animation
Introduction
.......................................................................................................................................................... 48
......................................................................................................................................................... 48
Creating Keyframes
......................................................................................................................................................... 50
Property Tweening
......................................................................................................................................................... 51
Mesh Animations
......................................................................................................................................................... 52
Using Skinned Meshes
......................................................................................................................................................... 52
Scripting
.......................................................................................................................................................... 53
Introduction
......................................................................................................................................................... 53
Script Editor
......................................................................................................................................................... 54
Overview
Effects
......................................................................................................................................... 54
.......................................................................................................................................................... 56
Introduction
......................................................................................................................................................... 56
Using Lens Flare
......................................................................................................................................................... 56
Using Video
......................................................................................................................................................... 57
Using Water
......................................................................................................................................................... 58
Using Shadows......................................................................................................................................................... 59
Quick-Editing Bitmaps
.......................................................................................................................................................... 60
Introduction
......................................................................................................................................................... 60
Using the Bitmap
.........................................................................................................................................................
Editor
60
Quick-Editing Sounds
.......................................................................................................................................................... 62
Introduction
......................................................................................................................................................... 62
Using the Sound
.........................................................................................................................................................
Editor
62
Database Access .......................................................................................................................................................... 63
Introduction
......................................................................................................................................................... 63
3 Reference...................................................................................................................................
Guide
65
Dialogs
.......................................................................................................................................................... 65
Menu Reference
.......................................................................................................................................................... 66
Director
.......................................................................................................................................................... 66
Menu Reference
......................................................................................................................................................... 66
Director Windows
......................................................................................................................................................... 67
Build Image Sequence
......................................................................................................................................................... 68
Build AVI/GIF ......................................................................................................................................................... 69
Adding Definitions
......................................................................................................................................................... 70
Director Properties
......................................................................................................................................................... 71
Data
......................................................................................................................................................... 75
Data Source Properties
......................................................................................................................................... 75
Data Set Properties ......................................................................................................................................... 78
Scene Editors
.......................................................................................................................................................... 80
Common Windows
......................................................................................................................................................... 80
Fonts
......................................................................................................................................................... 81
Edit Keyframes ......................................................................................................................................................... 81
2D Scene Editor......................................................................................................................................................... 83
Menu Reference
......................................................................................................................................... 83
II
III
DX Studio™ Help
Object Properties
......................................................................................................................................... 84
Add New Object
......................................................................................................................................... 85
Scene Properties
......................................................................................................................................... 86
Windows
......................................................................................................................................... 89
3D Scene Editor......................................................................................................................................................... 90
Menu Reference
......................................................................................................................................... 90
Material Properties
......................................................................................................................................... 91
Add New Object
......................................................................................................................................... 93
Chart Settings
......................................................................................................................................... 93
Effects
......................................................................................................................................... 94
Light Properties
......................................................................................................................................... 95
Look At
......................................................................................................................................... 97
Rotation Degrees
......................................................................................................................................... 97
Scene Properties
......................................................................................................................................... 98
Sound Usage
......................................................................................................................................... 101
Windows
......................................................................................................................................... 102
Bitmap Editor
Menus
Sound Editor
Menus
.......................................................................................................................................................... 103
......................................................................................................................................................... 103
.......................................................................................................................................................... 105
......................................................................................................................................................... 105
Script Reference .......................................................................................................................................................... 106
Color
......................................................................................................................................................... 107
data
......................................................................................................................................................... 108
Events
......................................................................................................................................................... 108
Face
......................................................................................................................................................... 110
File
......................................................................................................................................................... 111
layers
......................................................................................................................................................... 112
layer
......................................................................................................................................................... 112
Keyframe
......................................................................................................................................................... 113
keys
......................................................................................................................................................... 114
objects
......................................................................................................................................................... 114
object
......................................................................................................................................................... 114
Particle
......................................................................................................................................................... 119
Material
......................................................................................................................................................... 120
Math
......................................................................................................................................................... 121
media
......................................................................................................................................................... 122
meshes
......................................................................................................................................................... 123
mesh
......................................................................................................................................................... 123
network
......................................................................................................................................................... 124
NetworkSet
......................................................................................................................................................... 124
Rotation
......................................................................................................................................................... 125
scenes
......................................................................................................................................................... 126
scene
......................................................................................................................................................... 127
Sequence
......................................................................................................................................................... 129
shell
......................................................................................................................................................... 131
send
......................................................................................................................................... 131
sounds
......................................................................................................................................................... 132
sound
......................................................................................................................................................... 132
Subgroup
......................................................................................................................................................... 133
system
......................................................................................................................................................... 134
contextMenu
......................................................................................................................................... 135
exit
......................................................................................................................................... 136
file
......................................................................................................................................... 137
load
......................................................................................................................................... 138
Contents
IV
registry
......................................................................................................................................... 138
restart
......................................................................................................................................... 139
script
......................................................................................................................................... 139
window
......................................................................................................................................... 140
ui
......................................................................................................................................... 141
hitInfo
................................................................................................................................... 142
textures
......................................................................................................................................................... 143
Texture
......................................................................................................................................................... 143
Vector
......................................................................................................................................................... 144
Vertex
......................................................................................................................................................... 144
RotationMath ......................................................................................................................................................... 145
UtilMath
......................................................................................................................................................... 145
VectorMath
......................................................................................................................................................... 146
Other Functions .......................................................................................................................................................... 147
XML Reference
.......................................................................................................................................................... 147
Part V DX Studio™ Player
148
1 Overview
...................................................................................................................................
148
2 Debugger
...................................................................................................................................
148
3 Redistributing
...................................................................................................................................
DX Studio™
149
4 Kiosk Mode
...................................................................................................................................
150
Part VI DX Studio™ ActiveX
151
1 Overview
...................................................................................................................................
151
2 Embedding
...................................................................................................................................
in FrontPage
152
3 Embedding
...................................................................................................................................
in Internet Explorer
154
4 Embedding
...................................................................................................................................
in PowerPoint
154
5 Embedding
...................................................................................................................................
in Visual Studio
155
6 COM Interface
...................................................................................................................................
157
DXStudioPlayer .......................................................................................................................................................... 157
Methods
......................................................................................................................................................... 157
GetScene
......................................................................................................................................... 157
IsKeyDown
......................................................................................................................................... 158
DirectorScriptExecuteFunction
......................................................................................................................................... 158
DirectorScriptGetVariable
......................................................................................................................................... 158
DirectorScriptSetVariable
......................................................................................................................................... 158
Send
......................................................................................................................................... 159
NetworkSend
......................................................................................................................................... 159
NetworkOnlyBegin ......................................................................................................................................... 160
NetworkOnlyEnd
......................................................................................................................................... 160
SendAndWaitForCapture
......................................................................................................................................... 160
UseExistingWindow ......................................................................................................................................... 161
UseExistingDevice ......................................................................................................................................... 161
GetDevicePointer
......................................................................................................................................... 161
RenderLock
......................................................................................................................................... 161
RenderUnlock
......................................................................................................................................... 161
GetPlayerTime
......................................................................................................................................... 161
Properties
......................................................................................................................................................... 162
src
......................................................................................................................................... 162
Version
......................................................................................................................................... 162
IV
V
DX Studio™ Help
NetworkInstanceId ......................................................................................................................................... 162
NetworkDocumentId......................................................................................................................................... 163
NetworkGroupId
......................................................................................................................................... 163
ManualCreateAndUpdate
......................................................................................................................................... 163
CacheDirectory
......................................................................................................................................... 164
Password
......................................................................................................................................... 164
CustomStreamBackgroundCol
......................................................................................................................................... 164
CustomStreamLogoURL
......................................................................................................................................... 164
HideInactiveInfo
Events
......................................................................................................................................... 165
......................................................................................................................................................... 165
FrameUpdate
......................................................................................................................................... 165
Load
......................................................................................................................................... 165
Receive
Layer
......................................................................................................................................... 165
.......................................................................................................................................................... 166
Methods
......................................................................................................................................................... 166
MoveUp
......................................................................................................................................... 166
MoveDown
......................................................................................................................................... 166
Properties
......................................................................................................................................................... 166
Visible
......................................................................................................................................... 166
Index
NetworkSet
......................................................................................................................................... 167
.......................................................................................................................................................... 167
Methods
......................................................................................................................................................... 167
Send
......................................................................................................................................... 167
GetDocumentIdArray......................................................................................................................................... 167
GetInstanceIdArray ......................................................................................................................................... 168
Properties
......................................................................................................................................................... 168
Id
Scene
......................................................................................................................................... 168
.......................................................................................................................................................... 168
Methods
......................................................................................................................................................... 168
AddWorldObject
......................................................................................................................................... 168
GetSoundEffect
......................................................................................................................................... 169
GetWorldObject
......................................................................................................................................... 169
GetWorldObjectIdArray
......................................................................................................................................... 170
GetObjectDef
......................................................................................................................................... 170
RemoveWorldObject......................................................................................................................................... 171
ScriptExecuteFunction
......................................................................................................................................... 171
ScriptGetVariable
......................................................................................................................................... 171
ScriptSetVariable
......................................................................................................................................... 172
SetMediaVolume
......................................................................................................................................... 172
Properties
......................................................................................................................................................... 172
CacheDirectory
......................................................................................................................................... 172
WorldObject
.......................................................................................................................................................... 173
Methods
......................................................................................................................................................... 173
SetPosition
......................................................................................................................................... 173
SetScale
......................................................................................................................................... 173
SetRotation
......................................................................................................................................... 174
SetColor
......................................................................................................................................... 174
GetPosition
......................................................................................................................................... 175
GetScale
......................................................................................................................................... 175
GetRotation
......................................................................................................................................... 175
GetColor
......................................................................................................................................... 176
PerformClick
......................................................................................................................................... 176
ScriptExecuteFunction
......................................................................................................................................... 177
ScriptGetVariable
......................................................................................................................................... 177
Contents
VI
ScriptSetVariable
......................................................................................................................................... 177
SetSequence
......................................................................................................................................... 177
SetAnimation
......................................................................................................................................... 178
SetText
......................................................................................................................................... 178
Properties
......................................................................................................................................................... 179
Id
......................................................................................................................................... 179
Text
......................................................................................................................................... 179
Opacity
......................................................................................................................................... 179
Timer
......................................................................................................................................... 180
Type
......................................................................................................................................... 180
Visible
......................................................................................................................................... 180
SoundEffect
.......................................................................................................................................................... 181
Methods
......................................................................................................................................................... 181
Play
......................................................................................................................................... 181
PlayLooped
......................................................................................................................................... 181
Stop
......................................................................................................................................... 181
SetVolume
......................................................................................................................................... 182
Set3DPositionAndVelocity
......................................................................................................................................... 182
Properties
......................................................................................................................................................... 182
Part VII Other Applications
183
1 DX Studio
...................................................................................................................................
Server
183
2 DX Studio
...................................................................................................................................
in Visual Studio
183
3 FishCube
...................................................................................................................................
184
Part VIII Appendix
185
1 Freeware
...................................................................................................................................
Limitations
185
2 KeyNames
...................................................................................................................................
185
3 DX Studio
...................................................................................................................................
File Format
185
Index
187
VI
1
1
DX Studio™ Help
Welcome to DX Studio™
Welcome to DX Studio! DX Studio™ is a suite of tools that enable you to mix 2D
images, 3D objects, sound and video together to produce interactive documents for use
in MS Office or .Net applications, EXEs or CD-ROMS or for the web.
For newcomers to the product, we'd strongly recommend the Getting Started section.
New and existing users may be interested in the new range of Tutorials that are
available.
DX Studio™ Getting Started
A great place to start learning how to use DX Studio from scratch.
DX Studio Tutorials
How to use the Interactive Tutorial system, plus a some written tutorials.
DX Studio™ Editor Manuals
Learn more about building and editing interactive documents in the feature rich
studio.
DX Studio™ Player Manual
More information on how you can interact with the documents you've created
with DX Studio™.
DX Studio™ Player ActiveX Manual
Information on how to embed documents into other applications, or publish on
the web.
Redistributing DX Studio™
Find out how to copy and share DX Studio™ documents.
Copyright Notice
Copyright © 2006 Worldweaver Ltd.
All Rights Reserved.
The software described in this file is provided under a license agreement and may be
used only in accordance with the terms of the agreement as defined during the setup
application.
Getting Started
2
2
Getting Started
"Hmm. DX Studio looks pretty complicated..."
A Newuser
DX Studio™ may appear at first glance to be a large and complex product, but it can be
easily mastered.
The following pages of this section describe how the software is linked together so you
produce interactive documents quickly and easily.
Please click the 'Next' button at the bottom of the page to continue.
Help is always one key away! Don't forget you can get context sensitive help at
any time. Hit F1 when presented with any dialog box for instant help.
If you are familiar with similar products, please look out for
labels - they will
give you the information you need to get started as quickly as possible.
2.1
Installation
If you have already installed DX Studio, please click here to continue to the next
section.
Installation Procedure
· Insert the DX Studio™ CD-ROM, or launch the web setup
program from www.dxstudio.com.
If you're installing from the web, the following dialog will be
displayed, and only missing components will be downloaded.
3
DX Studio™ Help
· Please wait while your machine is checked and any necessary upgrades are installed.
This may take from a few minutes to several hours depending on the particular
configuration of your machine and speed of your connection. You can suspend and
resume the download at any time.
· You will be prompted if you need to upgrade your machine to DirectX 9.0c (October
2006 edition) or the .Net Framework 2.0. DirectX 9 is a backwards compatible
upgrade, and will not affect any of your existing DirectX applications. You can also
remove the .Net Framework at any time from the Add/Remove Programs section in
the Control Panel.
· The install procedure will then display a welcome page for DX Studio™.
· Click 'Next' to continue.
· Please read the license agreement carefully. The software described in this file is
provided under a license agreement and may be used only in accordance with the
terms of the agreement as defined during the setup application.
· In the next step, you can choose where to install the program to on your hard drive.
· To accept the default, just click 'Next'.
· Confirm that your installation details are correct and click 'Next' again.
· The software will now be installed. During installation, the DX Studio Player will also
be installed. The player allows you to view your documents either standalone or
embedded in another application.
· Press 'Finish' to complete installation. If a reboot is required, please close any other
open documents and reboot straight away. Otherwise you're now ready to run DX
Studio from it's folder in the Programs menu.
System Requirements
Minimum Requirements
1Ghz Pentium III processor
Microsoft Windows XP/2000
256Mb RAM
Getting Started
4
1024x768 desktop resolution at 32-bit colour depth
64Mb graphics card
200Mb free hard disk space
Recommended Specification
2Ghz Pentium IV processor
Microsoft Windows XP
512Mb RAM
1600x1200 desktop resolution at 32-bit colour depth
128Mb graphics card
400Mb free hard disk space
Software Prerequisites
Microsoft DirectX 9.0c
Microsoft .Net Framework 2.0
Note: These are the requirements for using the DX Studio editing suite. The
standalone player has much lower requirements, and does not need the .Net
framework.
Once you have successfully installed DX Studio™, click on the 'next' button below to
continue.
2.2
Exploring the Software
After the installation process is complete, you can run DX Studio™ for the first time. A
good place to start exploring the software is the 'examples' section.
Exploring the Software
Running for the first time
· Launch the DX Studio™ program by either double clicking the shortcut on your
desktop, or by selecting the program through the Start Menu.
· If this is the first time you have run the program, you will be asked whether you'd like
to subscribe to the DX Studio newsletter. We recommend you join the mailing list as
it's an infrequent (once every couple of months) but useful way to keep up to date
with the latest developments.
· The program will default into Freeware Edition, but if you've purchased Standard or
Pro, just run the license file (double click it) before launching DX Studio and the high
level features will be unlocked.
· The main window will then be displayed, along with the following welcome screen. (If
you don't get the welcome screen, go to the menu Help->Welcome).
5
DX Studio™ Help
From here you can browse the help files by choosing 'User and Reference Guides', view
examples by choosing 'Examples', or start using the product by just pressing Close.
Loading the examples
To get started, several demo documents have been created for you to load and explore.
· If you haven't got the Welcome screen up, go to the Help menu and choose
'Welcome...'
· You can hover the mouse over an example file on the left to get it's description. Just
click one the file to play the example, or click the menu dropdown to the right of it to
open it for examination in the editor.
· If you play the example, a window will pop up. Some examples can be explored by
clicking objects with the left mouse button, or navigating using the cursor keys and
the right mouse button.
· To exit the preview, press ALT+X .
· For examples of embedding documents in MS Word, MS Powerpoint and MS Visual
Studio, click the Coding Examples button in the 'Other Examples' section of the
Welcome dialog.
Getting Started
2.3
6
DX Studio Documents
Before you get started on the tutorials, its worth knowing how a document is
constructed.
A single DX Studio document can contain any number of 2D or 3D scenes, each with
their own graphics and sounds.
The top level in a document is responsible for the organisation of the scenes. These
can be layered on top of each other or displayed in sequence. At its simplest, a
document has a single layer showing the view from a camera in a single scene.
The diagram below shows the structure of a DX Studio document...
Each part of a document has its own editor. By double clicking a scene, an editor will
appear for it on the tab bar (shown below). To switch between editors, just click the
tab for the scene or top level document that you want to edit.
7
DX Studio™ Help
Now that you know how a document is constructed, please click the 'next' button below
to start the first tutorial...
3
Tutorials
3.1
Introduction
Tutorials in DX Studio are now fully interactive and embedded inside DX Studio itself!
To active the tutorial system, go to the Help menu and check the menu item
"Interactive Tutorials". This will bring up the following sidebar:-
Tutorials
8
Click a tutorial from the sidebar on the right to begin, or hover over a tutorial in the list
to get a quick summary. Always check the difficulty level of the tutorial is suitable for
how much you've learned so far.
When you're ready, press the Start button to begin a tutorial. Make sure you save
anything you're working on first as progressing through a tutorial will require a new
document.
At the end of each step, press the Next button to advance to the next one. When you
press the button, the tutorial system will check what you've done so far, and if there's a
difference it will alert you. You can however still proceed to the next step anyway, in
which case DX Studio will fix any problems automatically.
When a tutorial is finished, just select another tutorial from the list or close the tutorial
bar via the Help menu.
More tutorials are being published all the time - click the Online Library button to visit
the DX Studio library to browse what's available.
3.2
Other Tutorials
New tutorials will appear in the Interactive Tutorials sidebar, but for reference we've
included older tutorials this section.
9
3.2.1
DX Studio™ Help
Building a Porfolio Application
Note: Some screenshots and descriptions in this tutorial refer to an earlier
version of DX Studio, but this tutorial has been included as useful archived
content.
In this tutorial we'll be using DX Studio to generate an interactive portfolio, showing off
a skinned mesh created in an earlier issue of 3D World magazine by Chris Ollis,
although you could use any model you choose.
In order to try this tutorial you should have a basic understanding of copying and
pasting in Windows, using toolbars to perform select and move operations, and
selecting objects by either clicking or dragging with the mouse. DX Studio also uses a
multi-document workspace that can be navigated through using the tab bar below the
main menu.
During this tutorial you will need to use various extra resources (bitmaps, textures and
script) that can be found in a ZIP file at the following address. Please download and
save these resources for loading into DX Studio as needed.
http://www.dxstudio.com/examples/portfolio_tutorial_resources.zip
STAGE ONE | Setting the scene
1. To begin, launch DX Studio. Close the Welcome screen, and in the Add New Scene
dialog, choose to 'Create a new 3D scene...'. Press Next, then Finish to accept the
defaults.
2. In the empty 3D scene editor, find the 'Meshes' window (bottom right), and click the
'Add Mesh' button. Choose the 'character' file from the library.
Tutorials
10
3. You should now be able to see your model in the 3D world, and now would be a good
time to test the 'preview' feature. Press the F12 key and the editor will pop up a player
window. Navigate around the model using W,S,A,D on the keyboard, and right drag in
the window to turn the camera. Press ESCAPE to exit the preview.
4. Now let's add more features in the 3D scene. Near the 'Meshes' window tab is a tab
that displays the 'Environments' window. In that window press the 'Add Environment'
button and from the dropdown list under 'Load from library' choose
'hills_and_blue_sky_1024.dxenv'. Answer 'Yes' to the question that follows about
setting this environment as the background.
11
DX Studio™ Help
5. Find the 'Objects' window on the left, and dropdown the 'Add Object' menu. Choose
'Camera' to add another camera to the scene, then repeat so there are 3 cameras. By
right dragging in the viewport you can pan the camera selected in the dropdown at the
top of the viewport window. Press the 'P' key then left drag to pan/track the camera, or
the 'Z' key to zoom/dolly it.
6. Using the camera tools described in the previous step, position the three cameras in
different places around the model. Use the dropdown at the top of the window to
change the camera currently displayed in the viewport. If another camera is getting in
the way of your view, click the checkbox next to the camera in the objects list to hide it
from being drawn.
STAGE TWO | The 2D overlay
Tutorials
12
7. Go back to the top level (Director level) by clicking the 'Untitled' tab in the top left of
the window. You can use this tab bar to switch between different scenes and the top
document at any time. Now would also be a good point to save your progress using the
'Save As' option in the 'File' menu.
8. Find the 'Scenes' window in the bottom right and press the 'Add Scene' button to add
another scene. This time, select 'Create a new 2D scene from scratch' and press Next,
then Finish. This time a 2D scene editor window will appear.
13
DX Studio™ Help
9. In the 'Bitmaps' window in the bottom right of the editor, press the 'Add Bitmap'
button and choose the 'Load from file' option. Browse to the resources folder for this
tutorial and add the 'paneloverlay.png' file. It should then appear both in the 'Bitmaps'
list and in the viewport.
10. Press the 'Add Bitmap' button again and add all of the other bitmap resources from
the same folder in turn. If you add any bitmaps twice by mistake, just find them in the
Bitmaps list and press the red delete button to remove them, and answer 'yes' to
removing the object too.
Tutorials
14
11. Now you can position the bitmaps on the background as in the screenshot using the
Move tool (M). Don't worry about having two 'evil' and 'good' buttons at this stage as
we'll come back to this later. If you're having problems arranging them try switching
off the 'Snap edges' option in the 'Grid' tab of the Edit -> Scene Properties dialog.
12. With the 'panelbutton_220x50_1' object selected, press CTRL+D to duplicate it, and
move the duplicate below the original button. Do this so you have 4 buttons, one below
the other as in the screenshot. You can use the Position page of the Object Properties
window to help get the coordinates exactly right, or also the 'Align Centres' button on
the left of the window.
STAGE THREE | Scripting
15
DX Studio™ Help
13. Now it's time to make these buttons actually do things. With the 'changecamera_1'
object selected, find the 'Object Properties' window (top right) and click on the script
icon (hover over the icons for a description) to bring up the 'Script' page. Click the
'Edit' button on the bar to bring up the script editor.
14. In the editor, find the 'Add Event Handler' dropdown in the top right, and select the
'onClick' event. Before we can add content to this event, we need to define some more
functions for the 3D. Open the 'scene_1_script.txt' file from the resources for this
tutorial in Windows NotePad, select all the script (CTRL+A) and copy it to the clipboard
(CTRL+C).
Tutorials
16
15. Back in the DX Studio script editor (CodePad), double click the scene_1 tree node in
the Script Browser window to edit the 3D scene's script, click in the code window and
press CTRL+V then CTRL+S to save the code. Next, click the 'changecamera_1 Object
Script' tab at the top of the script editor to go back to the onClick event and type
scenes.scene_1.script.nextCamera(); inside the curly braces.
16. Hit F12 to preview the scene, and you should now be able to click the camera icon
to switch between all 3 cameras in the 3D scene. You might notice the centre of the 3D
scene is offset from the display window, but this can now be solved in the next step.
17
DX Studio™ Help
17. Click the top left (Director level) tab in the corner of the main DX Studio window to
return to the top level of the document. In the 'Layers' window select 'layer_1', then in
'Layer Properties' window (top right), set the position of the layer to 15,12 and the size
to 535,578 using the up/down spinners. Hit preview again to see the improvement.
18. To avoid the 3D scene ever being stretched, click the 3D scene in the top tab bar
(or double click the 3D scene in the Scenes window), and go to the 'Scene Properties'
option in the Edit menu. Under the Size tab, select 'Auto adjust aspect' and press OK.
STAGE FOUR | Adding functionality
Tutorials
18
19. Now let's go back to the 2D scene editor (again use the tab bar at the top of the
window) and link some more buttons. For each of the four 'panelbutton' buttons, edit
the script and add an onClick event. These buttons are going to change the animation
on the model.
20. In the onClick event for the first button, add the code scenes.scene_1.objects.
character_1.animation="walk"; and repeat for the other buttons, changing the
animation in quotes to "lookaround","hitgut" and "wait". You can also use the 'Add
Object' button to add some text to the document to label these buttons with their
actions. To change the text use the 'Text' tab of the 'Object Properties' window.
19
DX Studio™ Help
21. Next we can add the script for the left and right arrows. Select the left_1 object
and press the 'Edit' button in the 'Script' tab of 'Object Properties'. Add event handlers
for onMouseDown and onMouseUp. For the down event, add the script scenes.
scene_1.script.turnLeft=true; and for the up event set the same value to be false.
Repeat for the right_1 object, using turnRight instead of turnLeft.
22. Finally we'll set up the good/evil buttons that change the texture maps on the
model. From the 'Objects' window, delete the 'good_off_1' and 'evil_on_1' objects (left
click and press the Delete key), but leave the bitmaps for them in the Bitmaps window.
Rename the remaining 'good_on_1' as 'good_button' and the 'evil_off_1' as
'evil_button'.
Tutorials
20
23. Edit the script for these buttons (from the Object Properties window) and copy and
paste the code from the resource files 'good_button_script.txt' and 'evil_button_script.
txt'. Finally, go to the 3D scene, and in the 'Resources' window (bottom left) click the
'Add Resource' button to add 'Body_02.jpg' and 'Head_02.jpg' from the 'textures' folder
of this tutorial's resources. This will make the alternative texture maps available for the
scripts.
24. That's it! Save the document and from the 'Tools' menu choose 'Build EXE'. Press
the 'Browse' button to set the name and location for the output EXE and click 'Build'.
The single EXE produced contains all the resources needed to play back the document
on another PC, so you can just copy this file to a CD-ROM or send zipped up via email.
For ActiveX web publishing, you can try the Build HTML option, again from the Tools
menu. Just browse to a folder where you want to generate the required files and click
'Build'. A preview of the page in Internet Explorer will then be launched automatically.
21
3.2.2
DX Studio™ Help
Import and Export
These tutorials deal with getting different types of media in to and out of DX Studio.
Please click on the 'next' button below to start the first tutorial.
3.2.2.1
Models from 3D Studio Max
If you don't plan to use 3D Studio Max for modelling, please click here to go on to the
next tutorial.
For the best results in exporting models from 3DS Max, you need to download a free
export plugin such as the Panda DirectX exporter...
http://www.andytather.co.uk/Panda/directxmax_downloads.aspx
· Copy the plugin to the 'plugins' directory of your 3DS Max installation and launch the
application.
· Create/load your model and choose 'Export...' from the file menu.
· Choose the 'Panda DirectX' export format, press OK, and you should see the
following dialog...
You need to (at least) export the mesh definition, materials and geometric objects, and
should also export normals and mapping coordinates.
The 'Include Animation' will export position, rotation and scale animations on the
objects in the scene which are loaded as 'Mesh Animations' in DX Studio.
Tutorials
22
If you have a biped with a physique modifier, you can also export 'Bones', which will
also be understood by DX Studio.
The default options under the 'Animation' tab above are usually OK.
For textures, converting the texture map to PNG is usually a good idea where alpha
channels are used, or to JPG where the textures are always 100% opaque.
23
DX Studio™ Help
Use 'binary with compression' as the file type (although all are supported), and usually
export the entire sub frame hierarchy as this is loadable by DX Studio.
Always convert the coordinate system to the left handed axis.
· Once you have configured the exporter as above, click OK and the export process will
begin.
· That's it! You can then just drag the newly created X file into the DX Studio meshes
window, or import the mesh using the 'Add Mesh...' button.
3.2.2.2
Importing Other File Formats
DX Studio contains filters to load various foreign file formats and convert them into
native .dxmesh or .x format.
The following formats can be imported directly...
e Format
Extension
3D Studio (.3ds, .asc, .prj)
AutoCAD DXF (.dxf)
Imagine (.iob)
Turbo Silver (.ts)
LightWave (.lwo)
Lightscape (.lp)
Maya (.rtg)
RealiMation Version 4.1 (.rbs)
RenderWare (.rwx) (ASCII only)
Tutorials
24
Sculpt (.scene)
StereoLithography (.stl)
trueSpace (.coa, .cob)
VideoScape (.geo)
VRML 1.0 & 2.0 (.wrl) (ASCII only)
Wavefront (.obj)
XGL, ZGL (.xgl, .zgl)
XYZ (.xyz)
To load a file of this format, create a 3D scene and choose 'Add Mesh...' in the 'Meshes'
window. Select your file from the list and click OK.
3.2.3
Scripting
These tutorials deal with using script to create interactive content in DX Studio.
The script language used by DX Studio is the industry standard ECMAScript (otherwise
known as JavaScript). JavaScript is not the same as Java, which requires special
components and libraries in order to function. Script is parsed and executed inside the
DX Studio Player as needed; its simple yet powerful syntax being ideal for high level
control of media in DX Studio documents.
If you are completely new to JavaScript, you may want to read the Scripting
Introduction to get an idea of the structure of the language before starting these
tutorials.
3.2.3.1
Hello World
Where would an application be without the "Hello World" example? We continue the
tradition by starting with this simple example of using script...
· Create a new document, and create a new 3D scene inside it. Choose the 'Edit
Scene Script...' command from the 'Edit' menu in the 3D scene editor.
· In the Source Editor, choose 'onInit' from the 'Add Event Handler' drop down list.
You should now see the following code in the editor...
function onInit()
{
}
This function will be called once when document is initialized (onInit). For this
example, we're going to tell it to print a message in the player's console when this
initialization happens.
· Add the following line of code inside the onInit function...
print("Hello world!");
25
DX Studio™ Help
Your source code should now look like this...
function onInit()
{
print("Hello world!");
}
· That's it! To test it works, hit F12 to preview the document. "Hello world!" should be
printed in the console when the document is loaded.
You can also create an onInit function in the Director level (for the whole document) or
at object level (for an individual object).
3.2.3.2
Events
In the previous example, we created a function that was called when the document was
initialized (onInit), but there are many other events that we can handle.
This time we're going to handle what happens when an object is clicked with the
mouse...
· Create a new document with a new 3D scene.
· Find the 'Create' window to create a new 3D shape. Click the Box button (a cube) to
begin shape creation.
· Choose some sizes for the box (or just use the defaults), and click the 'Create' button
at the bottom of the form.
· The box should now be created and selected, and the Object Properties window will
have come to the front. Click the 'Script' tab in this window.
· At the bottom of the Script panel is an 'Edit' button. Press the button to bring up the
script editor.
· In the 'Add Event Handler' dropdown, choose 'onClick' to insert the code to handle the
click event.
· Now add some code that's going to specify what to do when the object is clicked...
function onClick()
{
object.pos.x+=100;
}
Here we're accessing the properties of the current object using the 'object.' reference.
One of those properties is 'pos' which determines the position of the object in the world.
A position property also has properties itself of 'x','y', and 'z', represeting the different
axes.
The operator '+=' in 'object.pos.x+=100' is equivalent to 'object.pos.x = object.
pos.x + 100'. This means we're adding 100 to the x position of the object every time
it's clicked.
· That's it! Try this out by pressing F12 to preview and clicking the box.
Tutorials
26
Other events that can be handled are listed here.
3.2.3.3
Variables
With every script comes storage space for variables. These can be temporary if you
declare them within a function or persistent if you declare them outside of a function.
· Create a new document, with a new 3D scene inside it. Create a box (as described
before) using the Create window, and attach the following script to the object from
the 'Object Properties' window...
var counter=0; // declare a variable called counter and initialize it to zero
function onClick()
{
counter++; // increment the counter every time you click
print("Counter is now "+counter);
}
Notice you can specify the initial value of a variable. These values will be assigned as
the script is compiled in the player, before even the onInit function is called.
· Hit F12 to preview. Every time you click the object, the counter will increase by one.
You can access variables either in functions of the same script (as above) or from other
scripts. For example, to access the counter from director level...
· Press ALT+W to get to the Window menu, then press '1' to return to the director
level.
· In the Edit menu choose 'Edit Director Script...' and add the following script...
var printedMessage=false;
function onUpdate()
{
if ((!printedMessage) && (system.timer>5.0))
{
print("At 5 seconds in, the value of counter is "+scenes.scene_1.objects.
box_1_1.script.counter);
printedMessage=true;
}
}
The script above prints out the value of a counter (as defined for example in the first
script) on an object called 'box_1_1' in scene 'scene_1'.
Similary, you could access the director level variables from an object in a scene...
var counter=0;
function onClick()
{
counter++;
print("Counter is now "+counter+", message has "+(system.script.printedMessage ? "" :
"not ")+"been printed");
}
27
DX Studio™ Help
This script not only increments the counter in the object, but checks the director level
variable 'printedMessage' and uses the boolean result to change the string sent to the
print function.
Note: If you have not come across the syntax before, it's useful trick in JavaScript to
avoid lots of 'if...else...' statements by putting:(<expression that evaluates to true/false> ? <result if true> : <result if false>)
e.g.
print(
3.2.3.4
((x>1) ? "x is greater than one" : "x is not greater than one")
);
Functions
As well as functions for handling events, you can define as many of your own functions
as you like. These can then be called from the same script or from other scripts to
carry out tasks.
This tutorial shows how you can add functions to perform your own tasks.
· Create a new document with a new 3D scene.
· Find the Sounds window in the scene editor and add the sound 'amazon_ok' from the
library.
· In the scene editor, go to the Edit menu and choose 'Edit Scene Script...'.
· Type the following into the source editor...
function makeNoise()
{
sounds.amazon_ok.play();
}
function spinAnObject(obj)
{
print("Spinning object: "+obj.id); // Read the id of the object passed to this
function.
obj.rotVelocity=new Rotation(0,1,0); // Apply a spin around the Y axis.
}
· Create a box (using the 'Create' window) and commit the shape.
· Go to the Object Properties window, Script tab, and click 'Edit'.
· In the source editor for this object's script, add an 'onClick' event...
function onClick()
{
scene.script.makeNoise();
scene.script.spinAnObject(object); // clever bit - pass this object as a parameter to
the scene's function.
}
· Select all of this script (press CTRL+A) and copy it to the clipboard for future use
(press CTRL+C).
· Now go back to the Create window and create another box, this time of a different
Tutorials
28
size/shape/colour.
· Go to the Object Properites window, script tab, and click 'Edit' for this object's script.
· Press CTRL+V to paste the same script you created for the previous object.
· Now hit F12 to preview. You should be able to click either box, and the scene level
functions will play a sound and spin box around.
3.2.4
Networking
These tutorials deal with linking DX Studio documents together over a network.
This is an advanced feature, and networking is only available in the Pro edition of DX
Studio.
3.2.4.1
Simple Networking
The first step in getting a network running is to enable networking in the Director level
properties for the document.
Create a new document, add an empty 3D scene, then go to the Director level and
choose 'Document Properties...'. Go to the 'Network' tab to get the network settings
page...
For the server enter demo.dxstudio.com, or if you're not connected to the Internet
29
DX Studio™ Help
press the 'Local Machine' button. Press the 'Default' button to set the port to 9620.
You can use the demo.dxstudio.com server for test purposes, but for commercial
releases you should install your own server.
Create a group identifier and a document identifier by pressing the 'Generate New'
buttons in the Advanced Settings box. Open the Windows Notepad application, and
copy and paste the group identifier into Notepad for later use.
Press OK to close the dialog, and then edit the Director level script (Edit Menu -> Edit
Director Script...)
Create a function called 'myNetworkTest' as follows:function myNetworkTest(val)
{
print("myNetworkTest called with value: "+val);
}
Save the document to a file (e.g. networktest1.dxstudio).
Now create another new document, add an empty 3D scene, and go to it's Director level
and choose 'Document Properties...'.
Check the link to other documents box, enter the same server as before and the same
port.
This time, paste the group identifier you saved before in Notepad into the Group
identifier text box. Use the 'Generate New' button to create a new document
identifier.
Press OK to close the dialog, and then edit the 3D scene by double clicking it in the
'Scenes' window.
Create a box with the 'Create' window, commit the shape by pressing the 'Create'
button and edit the script for the object (press 'Edit' in the Object Properties window).
Add the following script to the box...
function onClick()
{
network.Send("system.script.myNetworkTest('click time is "+system.timer+"');");
}
This will send a message to the myNetworkTest function when clicked.
Now save this document to another file (e.g. networktest2.dxstudio).
Navigate a file explorer in Windows to the folder where you saved the new documents.
Double click on both dxstudio files to launch them and click the box in the second
document.
That's it! Every time you click, a message is sent via the server to the first document
which should display a message.
Tutorials
4
DX Studio™ Editor
4.1
Introduction
30
The DX Studio editor is the main integrated development environment for building your
documents. Essentially, it allows you to build or import media and specify how it should
interact with the user.
If you're new to the product, please see the Getting Started section for an
introduction to the editor, and also try out some Tutorials before venturing further.
Information on the editor is divided into two sections:-
User Guide
A step-by-step guide to using the package for various tasks.
Reference Guide
Documentation on every menu function, dialog option and script language command.
Introduction
4.2
User Guide
This user guide details how to perform various tasks in the editor.
Director Level Concepts - What's going on at the top level of the DX Studio editor.
Building 2D Scenes - The 2D editor explained.
Building 3D Scenes - The 3D editor explained.
31
DX Studio™ Help
4.2.1
Director Level Concepts
4.2.1.1
Introduction
The top level editor, or Director level, is concerned with the layering and order of
display of scenes.
The first step in building any document is deciding the native size that you want to
create. By default, you are building a 4:3 aspect ratio document with a pixel resolution
of 800 by 600. You can change these settings by opening up the 'Properties...' dialog of
your document at director level. Any new scenes you create from this point will inherit
the size of the director document by default.
Then, you build the 2D and 3D scenes that you want to display in your document, and
return to the director level to arrange them.
Using the Workspace
DX Studio™ Editor
32
The first thing you need to do in creating a document is define a scene to display. You
can either load an existing scene, or create a new one, specifying if you want a 2D or
3D scene.
Once you have your scene, you can change the layer to display your scene from a given
camera position. The result show then appear in the workspace preview window, and
you can hit F12 to show the result in the player application.
Menu Reference: find out what each menu function does.
Introduction
4.2.1.2
Using Scenes
A DX Studio™ document is built up from scenes. These contain 2D or 3D media, and
can be linked together in sequence, or layered on top of each other to build a complete
document.
Loading an existing scene
· Find the 'Scenes' window. If it is hidden, it can be displayed by going to the Window
menu and choosing 'Scenes'.
· Click the 'Add Scene' button (the 'Add' icon in the Scenes window). This will display
the following dialog...
· You can then select to Browse for a .dxscene file, or just click one to load from the
library.
Creating a new scene
· As with loading an existing scene, find the 'Scenes' window and click the 'Add Scene'
33
DX Studio™ Help
button.
· In the 'Add New Scene' dialog choose the 'Create a new (2D or 3D) scene' option.
· The new scene will appear in the 'Scenes' window.
Viewing a scene
In order to show a scene, you need to define a Layer. By default in a new document, a
single default layer is created for you. To set the layer to display this scene, you should
use the Layer Properties window.
Using the drop down menus, you can select the scene, and location within that scene,
that the selected layer should display.
Once you have selected your scene you can preview the result by hitting F12.
4.2.1.3
Using Layers
Any number of scenes can be overlaid on top of each other. This is achieved through
the use of 'layers', where each layer has its own scene and camera.
Add a new layer
· Find the 'Layers' window. If it is hidden, it can be displayed by going to the Window
menu and choosing 'Layers'.
DX Studio™ Editor
34
· Click the 'Add Layer' button. A new layer will appear in the layers window.
· You can now set the scene and camera for this layer in the 'Layer Properties' window.
· That's it - this layer will be drawn on top of the previous layer.
You can change the order in which layers are drawn using the 'move up' and 'move
down' arrows in the layers window.
4.2.1.4
Using Resources
DX Studio™ files are based on the concept of 'resources' - which simply refers to a
collection of files. For example, a JPG texture map, a sound file, and an XML file are all
resources. You can think of the resource viewer as simply a ZIP file explorer, where
you can add and remove files from the archive.
Name - gives the filename (identifier) of the resource (there are no directory paths
when inside a document).
Date - shows the last time the file was modified.
Original Size - shows the file size before any compression.
Usage - shows how many times this resource is referred to by other resources.
External Link - shows the real location of the file if it is a link instead of an embedded
file.
Adding a new resource
· Find the 'Resources' window. If it is hidden, it can be displayed by going to the
Window menu and choosing 'Resources'.
· Click the 'Add Resource' button. A file selection dialog will appear.
· You can now select any number of files to add as resources. They do not need to be
of types recognised by the application, as resources are not active parts of the
document unless they are referred to.
35
DX Studio™ Help
4.2.2
Building 2D Scenes
4.2.2.1
Introduction
A 2D scene is the simplest type of scene that you can create. Coordinates are specified
in pixels, and bitmap images can be layered and aligned as in standard CAD packages.
A quick step-by-step guide to creating a 2D scene can be found in the interactive
tutorials, and more information on using scenes in general is available here.
Editor Overview
4.2.2.2
Editor Overview
You can edit the composition of 2D objects, data, animations and sounds in the 2D
Scene Editor.
Using the Workspace
You can add objects to a scene by clicking the Add button at the bottom of the 'Objects'
window on the left.
Tool Windows: find out what each tool window does.
Introduction
DX Studio™ Editor
4.2.3
Building 3D Scenes
4.2.3.1
Introduction
36
A 3D scene supports true three dimensional modelling and animation. Coordinates are
specified in floating point units.
More information on using scenes in general is available here.
Editor Overview
4.2.3.2
Editor Overview
You can edit the composition of 3D objects, data, animations and sounds in the 3D
Scene Editor.
Using the Workspace
You can add objects to a scene by clicking the Add button in the bottom of the 'Objects'
window on the left.
Tool Windows: find out what each tool window does.
37
DX Studio™ Help
Creating Shapes
4.2.3.3
Creating Shapes
The 'Create' window provides a range of different primitive shapes that can be
constructed. For example, clicking on the box will present the following options...
The number of segments determines how many faces you will get in the final object.
More faces improve the resolution of the shape, but can impact on performance. You
can see how many faces and vertices will be created in the 'Object Info' box at the
bottom.
The options above produce a box that looks like this...
DX Studio™ Editor
38
...where the 'smooth corners' option can be seen to shave off the edges in a single
segment. By increasing the segments used by 'smooth corners', you get a more
rounded edge.
These same principles apply to all of the primitives that you can create.
The 'Preset' dropdown will remember the parameters used for last shape created as the
'[last]' item. You can also store your own parameters by just typing a name into the
Preset box and pressing the 'Return' key. To delete a user preset, just select it from
the list and press the 'Delete' key.
Creating Terrain
4.2.3.4
Creating Terrain
The 'terrain' tool is a special type of tool allows the creation of landscapes by a
combination of a height map and a texture map.
39
DX Studio™ Help
To build a terrain, you need a height map. This is simply a bitmap where the
brightness of each pixel relates to it's height. So, black pixels represent the lowest
height possible, and white pixels represent the highest height.
A sample height map can be found in the library folder, usually C:\Program Files
\Worldweaver\DX Studio\library, as the PNG file 'heightmap_height.png'.
Secondly, you need a texture map that will be drawn over the mesh generated by the
height map.
A sample texture map can also be found in the library folder, as the PNG file
'heightmap_texture.png'.
The 'Add border' option creates an extra border around the height map of zero height.
This can be useful to give 'sides' to a terrain.
The number of faces/vertices produced depends on the number of samples across the
width and height. You should reduce the number of samples to produce the best
DX Studio™ Editor
40
balance of accuracy and speed for your model.
When you are happy with the result, hit the Create button to build the terrain. For the
sample maps, the following terrain will be built...
Modifying Shapes
4.2.3.5
Modifying Shapes
Shape modifiers take an existing mesh and apply transformations to it to produce a new
mesh. Unlike a simple scale or rotate, they alter the actual mesh data and so will affect
every instance of the mesh object in the scene.
For example, the 'twist' modifier has the following tool window...
The result of these parameters is a transformation, that if applied to a knight
chesspiece would look like this...
41
DX Studio™ Help
...where the mesh is twisted along the Y axis by 120 degrees over the height of the
object from the base upwards.
Most parameters can be 'flipped' by using the 'Flip' checkbox, so in this case rather than
twist the top, the bottom would be twisted like this...
To commit the current settings and make the modification, you must press the 'Accept'
button.
The 'Preset' dropdown will remember the parameters used for last accepted modification
as the '[last]' item. You can also store your own parameters by just typing a name into
the Preset box and pressing the 'Return' key. To delete a user preset, just select it
from the list and press the 'Delete' key.
4.2.3.6
Editing Subgroups
Every mesh contains one or more subgroups that hold individual parts of a model. You
can edit these by expanding the mesh object in the object list.
Subgroups do not have all the same properties as a full dx studio object, and so the
'Object Properites' window will change to reflect this when you have a subgroup
selected.
4.2.3.7
Materials
4.2.3.7.1 Introduction
Materials define the characteristics of a surface in a 3D scene. You can define your
materials at 'scene level' in the 'Materials' window. This set can be thought of as a
'palette' of materials that you can use to 'paint' items in your scene with.
DX Studio™ Editor
42
For a material to be displayed, it must be part of a mesh. In this example, we'll look at
the chessboard.dxmesh model...
Here you can see the model has 3 materials - a wooden border and two colours of
marble for the squares. To edit a material, just double click it. You can also drag
materials from the model's list into the scene's 'Materials' window (and vice versa) to
make copies of your commonly used materials.
To change the material on individual faces, expand the object's subgrounds in the tree
in the Objects window. Click on a subground that has a mesh attached, then click the
'face' button in the Object Properties window. You can now select and assign different
materials to different faces.
4.2.3.8
Particles
Particles are simple objects that usually exist in large numbers to create an effect.
Common types of particles include smoke, sparks, splinters and snow.
Once you have defined a particle in the 'Particles' window, you can create particles in
script using the following...
var p=new Particle(); // create a particle
p.pos=new Vector(100,100,100); // set the position
p.posVelocity=new Vector(0,-50,0); // set the velocity
See the Particle section in the reference guide for a list of all the available properties.
43
DX Studio™ Help
4.2.3.9
Level of Detail (LOD)
Environments are used for backgrounds in a 3D scene, typically for distant views of
mountains and the sky. Some surfaces may reflect the environment in them, giving a
shiny appearance.
In order to improve the speed of more complicated documents, it can be advantageous
to provide several different meshes representing different levels of detail of the same
object. The player can then choose a lower-resolution model when drawing the object
at a distance, and swap to a higher resolution model as the object gets closer.
This is supported in DX Studio by a special multi-level mesh type. To add one, right
click in the 'Meshes' window and choose 'Add Multi-Level Mesh' to bring up the following
dialog...
All you need to do to set up LOD switching is to first set the total number of levels you'll
be switching between.
Then, use the 'Level' field to set which level you're editing and set the maximum
distance for that level that the selected mesh will be displayed up to.
You can then drag this mesh into the viewport to add a LOD switching mesh to the
scene.
For more advanced usage you can also use the LOD system to improve the performance
for collision and shadows as described in the next section.
DX Studio™ Editor
44
4.2.3.9.2 Using LOD for collision and shadows
The LOD system can be used to improve the performance for collision and shadows by
examining a simpler mesh for these applications.
If you add a multi-level mesh as described here, you can set which level should be used
for collision detection/physics 'Physics' and which level for shadows 'Shadow' in the
dialog.
If you don't every want to actually draw the levels you use for these functions, uncheck
the 'Visible' box and the mesh will be used for reference purposes only.
4.2.3.10 Environments
Environments are used for backgrounds in a 3D scene, typically for distant views of
mountains and the sky. Some surfaces may reflect the environment in them, giving a
shiny appearance.
To create an environment, you either need a real source (such as a 360 degree
photography system like iPIX) or a virtual one (such as a 3D landscape generator
package) that can output cubemaps.
The actual map is just 6 textures representing each inside face of the cube stored in a
single file. If you're looking down the Z axis in the editor, the following will apply:-
45
DX Studio™ Help
+X = face to the right
-X = face to the left
+Y = face below
-Y = face above
+Z = face straight ahead
-Z = face behind
Images used for the cubemap faces should normally be a power of 2 in size, eg.
256x256, 512x512, or 1024x1024.
A good source for environments is Terragen - how to use it to create them is described
here.
4.2.3.10.2 Creating Environments with Terragen
This tutorial will create an environment that you can use as a background or for
reflections in a 3D scene. Once built, you can save/load your environments as '.dxenv'
files.
Open Terragen and create your landscape. To create a quick one for testing, click
'Landscape' to get the landscape window, click 'Generate Terrain', and accept the
defaults for a random terrain. You normally want the cube map to represent only a
distant view, so use the map editing tool to flatten out the terrain near to the centre of
the landscape (where you will put the camera).
In the Rendering Control window, click the camera settings... button, and set the zoom/
magnification to exactly 1. Place your camera somewhere in the middle of the terrain,
about a couple of metres above the surface.
Set the image size to be the same width and height, usually 512 x 512. For large
screen resolutions, a size of 1024 x 1024 is recommended.
Render 6 images using the following camera head and pitch orientations... (bank is
always 0)
Image
Image
Image
Image
Image
Image
1 : Head 0, Pitch 0 - save as 'mountains_posz.bmp'
2: Head 180, Pitch 0 - save as 'mountains_negz.bmp'
3: Head 90, Pitch 0 - save as 'mountains_posx.bmp'
4: Head -90, Pitch 0 - save as 'mountains_negx.bmp'
5: Head 0, Pitch 90 - save as 'mountains_posy.bmp'
6: Head 0, Pitch -90 - save as 'mountains_negy.bmp'
For convenience, a Terragen script can do all the camera changes and generate the 6
images automatically:InitAnim "C:\skybox", 1
Zoom 1
CamB 0
CamP 0
CamH 0
FRend
CamH 180
FRend
DX Studio™ Editor
46
CamH 90
FRend
CamH -90
FRend
CamH 0
CamP 90
FRend
CamP -90
FRend
Just copy and paste the script above into a plain text file, and save it as 'build_skybox.
tgs'. In Terragen, choose the 'Execute Script' function and select the file to build the
images. You can then rename the image files from skybox0001.bmp to
mountains_posz.bmp, etc. (they are in the same order as listed above). Note by
default this script will place the images in the 'C:\' directory - just change the first
parameter in the first line from "C:\skybox" to "C:\mypath\skybox" to store in a
different directory.
You can now create an environment in DX Studio and add the 6 images you created
where mountains_zpos maps to the +Z image, etc. It is recommended that you
convert the BMP images to JPEG for space saving - this can be done either in the DX
Studio Bitmap Editor or in an external application.
See Also
FishCube
4.2.4
Output Formats
4.2.4.1
Introduction
DX Studio documents can be exported for a number of different uses, including
standalone execution, integration in Visual Studio, web publishing or animation.
4.2.4.2
Building an EXE
You can build a single executable file that contains both your document and the DX
Studio Player by using the menu option 'Tools -> Build EXE...'.
Just click the Browse button to select the Output EXE filename that you want to save
the EXE to, and click 'Build'.
If you have the Pro edition, you can set the icon on the EXE by checking the custom
player icon box and browsing to an ICO file on the disk.
47
DX Studio™ Help
The EXE contains code to check for DirectX 9, and will prompt to download it if it is not
found. You do not need the .Net Framework or the managed DirectX extensions in
order to run the EXE.
4.2.4.3
Building for the Web
If you want to distribute a document for Windows PCs with IE, you can use the
embedded ActiveX control in your HTML.
The menu item 'Tools -> Build HTML...' will popup the following dialog...
Windows XP SP2 Users
DX Studio™ Editor
48
When you view a local HTML file, you may see the following message: "To help protect
your security, Internet Explorer has restricted this file from showing active content that
could access your computer. Click here for options…"
To bypass this message:1. Click on the message
2. Select "Allow blocked content"
3. Select OK in the Enable Active Content dialog to continue
To avoid seeing this message in the future, select the Tools->Internet Options… menu
in Internet Explorer. Select the Advanced tab, then scroll down to the Security settings.
Select the checkbox labeled "Allow active content to run files on My Computer".
4.2.4.4
Building Movies
For non-interactive content, you can also output to single or moving image formats.
For further information on the options available, please see:Build Image Sequence
Build AVI/GIF
4.2.5
Animation
4.2.5.1
Introduction
Animation brings to life your models by allowing you to specify their movement, scale
and rotation over time.
Every object can have any number of high level 'sequences'. For example, one
sequence could be a button sliding into the display, and another sequence could be the
button spinning away into the distance.
Each sequence has a duration measured in seconds, and can be looped (for example
with a spinning logo) or played once only (for entry/exit transitions).
The principles of animation apply to both 2D and 3D scenes, and use the same 'Edit
Keyframes' dialog. To access this dialog, select any object in 2D or 3D and press the
'Edit Sequences' button in the Object Properties window.
49
DX Studio™ Help
The first thing you need to do is to add a sequence to the object by pressing the 'Add
Sequence' button. You can then rename it to be relevant to the movement that you are
going to create, for example 'slide_in'.
You can then set the duration of the sequence, say to be 1 second. The 'Snap To' value
allows you to configure the time resolution at which you will be creating or moving
keyframes. Simply put, the duration is split into chunks of time, the size of which is
specified in the 'Snap To' put.
By default, the first sequence you create will be set to 'Auto play'. This means that the
sequence will be triggered as soon as the object that you are keyframing is created in
the player.
To trigger a sequence manually, you need to use script. For example...
function onClick()
{
object.sequence="slide_in";
}
...would trigger the sequence named 'slide_in' when the object was clicked.
You can also use script to link from the end of one sequence to the beginning of
another. This is achieved using the 'show' event, which is available in the script for the
selected keyframe.
function onShow()
{
object.sequence="spin_around";
}
Click here to continue on to the next step - Creating Keyframes.
DX Studio™ Editor
4.2.5.2
50
Creating Keyframes
Each sequence contains 'keyframes', which specify the value of a property (such as the
position, size, or rotation of the object) at a specified time.
The player then interpolates between these values to give a smooth and predictable
result in the player regardless of the final frame rate.
The keyframes you create are shown as black rectangles on the keyframe edit bar.
When you first create a sequence, the bar will not contain any keyframes...
To add a keyframe you can use either of two methods:The first method is to trigger a 'write' of any of the object's properties, either by
manipulating the object on the workspace using move/scale/rotate/etc. or by editing
the values in the 'Object Properties' window. Any properties that you change will be
stored as a keyframe at the currently selected time (shown by the vertical red line in
the keyframe edit bar).
The second method is to manually add a keyframe by right clicking on the time you
want the keyframe to created at in the keyframe edit bar. Choose 'Add Keyframe...'
from the popup menu.
51
DX Studio™ Help
Check the boxes of the properties that you want to define at the currently selected time
(where you right clicked). The selected properties will have their current values copied
into a new keyframe.
Property Tweening
4.2.5.3
Property Tweening
The interpolation performed by the player between property values stored in keyframes
is known as 'tweening'.
There are four basic types of tweening that can be used:Jump
The value 'jumps' straight to the value stored in the keyframe. There are no
intermediate steps.
Linear
The value moves in equal steps from one keyframe value to the next.
Stepped
The value moves slowly away from the first value, faster in the middle, and then slows
again to rest on the next value.
Quad
This takes a series of 4 values to produce a smooth movement between them all. The
mathematical term for the interpolation used is known as 'Catmull-Rom'.
DX Studio™ Editor
52
Different properties support different types of tweening. For example, the 'visible' flag
can only be 'true' or 'false', and so the only tween you could use for it would be 'Jump'.
To set the tweening on a property, select it from the 'Property' box in the keyframe
editor.
The 'tween in' parameter determines how this keyframe property is arrived at, and the
'tween out' parameter determines how the property changes into the next one. (ie. the
'tween out' of a keyframe property will be the same as the 'tween in' of the next
keyframe property).
Just click the tween method you want to use for the property at this keyframe by using
the buttons (hover the mouse over a button to get it's description). If you select
another keyframe, the same property will stay highlighted so you can set several
methods quickly. You can also select multiple properties and set all their tween
methods at the same time - just SHIFT+click in the 'Property' list.
4.2.5.4
Mesh Animations
In addition to the high level sequences, you can also have animations stored in your
mesh file. These will also be created as a result of exporting a model from a third party
product, such as 3D Studio Max, with animations included.
You can trigger these animations in script, for example...
function onClick()
{
object.animation="walk";
}
...would set an object's animation to the one named 'walk' when the object was clicked.
You view all of the available animations in the 'Edit Animation' window (check 'Edit
Animations' button in the 'Sequences and Animations' tab in the 'Object Properties'
window of the 3D scene editor).
These animations operate separately from the sequences, so you could have a character
moving along a path (set by the sequence) as the character walks (set by the
animation).
4.2.5.5
Using Skinned Meshes
DX Studio supports animated skinned & boned meshes. The process of generating a
skinned mesh is fairly complicated and should only be attempted by experienced
modellers.
Exporting from 3DS Max
53
DX Studio™ Help
After generating the biped and physique for your model, use an X file exporter such as
the free Panda tool referred to in the 'Third Party Tools' folder found under the start>programs->dx studio menu.
You will need to export bones and animation data with the full frame hierarchy. Also,
crucially, DirectX only supports a maximum of 4 blends per vertex/face, so make sure
your physique is initialised accordingly.
The animations on the mesh can then by triggered as with other X file animations.
4.2.6
Scripting
4.2.6.1
Introduction
To provide the highest level of control over your interactive documents, DX Studio
contains a comprehensive scripting language that is fully ECMAScript (i.e. JavaScript)
compliant.
If you are completely new to scripting or programming, you may wish to spend some
time reading up on general programming principles. Some free programming tutorials
can be found online, but we'll also cover the basics here.
The script language used in DX Studio is like a cut down version of JavaScript or C,
designed to provide the maximum control for the minimum amount of code.
The basics of the language can be summarized by the following rules...
· All executable code must be in a function block
A function block is denoted by a type keyword, the name of the function, and any
parameters the function requires.
See, for example, the following code...
function playSound()
{
sounds.warble.play();
}
The keyword (in blue) 'function' begins the function definition, the word 'playSound'
describes the name of the function, and the open and close brackets denote the
parameter list, which in this case means there are no parameters required.
The language is CASE SENSITIVE so be careful with your use of upper and lowercase
characters. DX Studio functions and variables have the first letter in lowercase and the
rest capitalized at the start of new words.
The open and close curly braces denote the body of the function block. You must
always match each open bracket or brace with the same number of close brackets or
braces.
In the body of the function is the statement 'sounds.warble.play();'. Each statement
must be separated with a semicolon ';', and should usually be placed on a separate line.
DX Studio™ Editor
54
As well as defining your own functions, there are some predefined functions that handle
various events...
onMouseDown - will be called when the mouse is pressed
onMouseUp - will be called when the mouse is released
onMouseMove - will be called when the mouse is moved
onKeyChange - will be called when then user presses or releases a key on the keyboard
· Commands are organized into collections
The key to neat and easily readable code is the use of a hierarchy of commands,
organized to collections.
For example, the system collection contains system level commands, the sounds
collection contains the names of all available sounds, and so on. Each member of the
collection may contain further sub-members, for example 'scene.media' contains further
members 'play','stop','back',etc.
To trigger a command in a collection, just use the full path of the command in the
collection as a statement - for example...
function onClick()
{
sounds.whizzpop.play();
}
Although most commands can be used like this, some also accept being used as the
target for an assignment (or l-value). An example of this would be...
function onClick()
{
system.window.width=640;
system.window.height=480;
}
...where the width and height of the player window are set by the script.
See the Script Reference section for a full list of commands.
4.2.6.2
Script Editor
4.2.6.2.1 Overview
The script editor is a custom built editor that provides syntax highlighting and instant
error reporting.
55
DX Studio™ Help
Using the Editor
Source Code Window
The top left window is the source code area, where the script is edited. Just click and
type in this window to enter your script. To align blocks of code, use the TAB key.
Tools Window
The window to the right is a helper window. You can add the script for an event
automatically with the 'Add Event Handler' drop down, or use the Useful Collections
drop down to get started with a statement.
As you type, a helper list box will show the possible properties for the object under the
cursor in the source code window. It does not show every possible command available,
but rather the members of the collection that you are in. For example, if you type...
sounds.
...in the source code window, the collection members box lists all of the possible sounds
that you could select. Then you just double click a sound to enter it automatically into
the code, or just hit RETURN.
Results Window
This window will show any script errors as you type. If there is a problem, the error will
DX Studio™ Editor
56
be underlined in red in the source window. You can click different errors to see where
they are in the code.
Tip: You can shift a block of script to the left or right by one tab stop by simply
selecting the lines to shift and pressing TAB to move right or SHIFT+TAB to move left.
Saving Changes
When you are happy with your script you should save the changes using the File->Save
menu option.
Writing Script
See the Script Reference section for information on the simple scripting language.
4.2.7
Effects
4.2.7.1
Introduction
Effects are used to add wow-factor to your documents. They can be added to objects,
scenes and documents, where each has different types of effect that apply. For
example, the water effect can only be applied to an 'effectplane' in a 3D scene.
The 'effectpoint', 'effectplane' and 'effectcube' objects are not themselves visible, and
serve as containers for effects. As implied by their names the 'effectpoint' is just a
point in either 2D or 3D space, an 'effectplane' is either a 2D rectangle or plane in 3D,
and an 'effectcube' only exists in 3D as a variable sized box.
To see what effects are available in your edition of DX Studio there's a tool in the help
menu called 'List All Installed Effects'.
Each effect has its own configuration dialog to set the parameters for the effect.
Effects are added to an object using the 'FX' button in the 'Object Properties' window.
Scene effects can be added in the 'Scene Properties' dialog, and director level effects in
the 'Director Properties' dialog.
4.2.7.2
Using Lens Flare
Lens flare is used to simulate the effect of bright light on a camera lens. It can be
added as an 'effect' to any object, but is usually added to lights.
57
DX Studio™ Help
To use flare, you need to set up a particle to contain all the different types of flare that
you want to use.
As an example, the white_flare.dxparticle file in the library shows a typical particle
suitable for a flare.
To get a flare going quickly:1. Create the flare images as frames in a particle (or just add white_flare.dxparticle
from the library).
2. Select the light you want to cause the flare (you may want to move this to a distant
point to represent the location of the sun to the viewer).
3. In the 'Effects' tab of the 'Object Properties' window, add the lens_flare effect.
4. Select the particle in the configuration dialog for the effect.
5. Hit F12 to preview.
For added realism, if the line of sight to the flared light is blocked by another object, the
entire flare will disappear. Also, the alpha of the flare is faded the more the viewer
turns from the flared light.
4.2.7.3
Using Video
You can play back video in DX Studio by adding a 'video' effect to an 'effectplane', or by
replacing a texture map in the scene using the 'videotexture' scene effect.
MPG or AVI are the best supported formats. AVI can use any codecs inside the file
itself, but if the AVI plays in Windows Media Player, it should play in DX Studio. There's
no file size/resolution restriction.
The simplest test is to add the movie to a scene as a LINKED resource (for speed), add
it to the media play list, create an effectplane, add the 'video' effect and hit F12 to
preview.
DX Studio™ Editor
4.2.7.4
58
Using Water
To use the water effect, you need to add an 'effect plane' to your 3D scene. Then, go
the 'Effects' tab in the Object Properties window. Click the 'Add Effect' button and
choose 'water' from the list. You will then be presented will the following dialog:-
The 'Wave Material' is the material to be used for the water's surface, and the 'Bottom
Materials' determines what is drawn under the wave to represent the bottom of the
water.
Click a material to edit it. If the wave material is 100% opaque the choice of bottom
material is irrelevant.
Note: For best results, add an environment into the Environments window first, then
use this environment on the wave material. The bottom material should also have a
texture map defined to show the refraction effects.
Water may be non-square by defining a shape using a black and white bitmap of 64x64
pixels (you may use any resolution, but it will always be resized to 64x64). The wave
will only be drawn where the white pixels in the shape's image are.
59
DX Studio™ Help
The 'Generator' determines how the waves are produced. A Generator Type of 'Random
Drop' simulates drops being added to the water's surface in a random position. For
greater control, you can define a 'Wave Trigger Bitmap' that allows any size or shape of
drops. The bitmap should be 64x64 pixels, where black pixels are no impact and white
pixels maximum impact, with all shades of grey in between also allowed.
Auto trigger is used to determine how often the wave should be triggered.
4.2.7.5
Using Shadows
There are two types of shadows now available in DX Studio.
The most commonly used type is the dynamic high frequency shadows, which produce
'hard edges'.
Dynamic Shadows
To switch this on, select an object and in the Object Properties window, click the
'Advanced' button.
You can now set whether the object casts or shows shadows (or both). If you don't
want shadows casting from some lights you can selectively disable them from the
shadow engine in the lights' property pages.
Shadowing does require some hardware support from pixel and vertex shaders, so you
will need a recent graphics card to get good results.
DX Studio™ Editor
60
PRT Shadows (Pre-computed Radiance Transfer)
This system is best suited to static open-air terrains as it uses a distant lighting model.
All of the mesh data must be in a single mesh, and as such it therefore cannot move
relative to other parts of the mesh at runtime.
To enable PRT, go to the Advanced button in the Object Properties window and check
the box for 'Light with PRT'. Click the 'Go' button to calculate the lighting for the mesh
and store the results in a special PRT file. At runtime, the PRT file will be loaded to
generate the lighting. If you change the structure of the mesh in any way, you should
recalculate the PRT file before launching the player.
4.2.8
Quick-Editing Bitmaps
4.2.8.1
Introduction
The quick-editor for bitmaps is designed to help you make simple changes to bitmaps
and their transparencies, or to view and edit how 3D mapping coordinates relate to
textures.
You can still use 3rd party applications to perform advanced edits - just go to the Edit>Copy function to copy the bitmap to the clipboard, paste it into your paint package,
perform the edits, copy it to the clipboard in your paint package, and go to Edit->Paste
to embed the result back in the DX Studio document.
The bitmap editor will not commit any changes that you make until you choose the
'Save' option from the file menu. This saves the bitmap into the scene's resources, but
will not affect any external files that you may have loaded the bitmap from. In order to
extract a bitmap file from DX Studio you should use the 'Export' option from the file
menu.
Using the Bitmap Editor
4.2.8.2
Using the Bitmap Editor
The bitmap editor can be activated by double clicking any resource that is an image file,
or by double clicking a bitmap in the 'Bitmaps' window.
61
DX Studio™ Help
There are some simple tools along the top of the window for selecting rectangular and
circular shapes and areas of similar colour. There is also a simple 'paintbrush' that
allows you to draw brush strokes onto the image. The size and fade of the brush can be
set in the 'Brush' window, and the colour of the brush can be selected in the 'Palette'
window. Any brush strokes only affect pixels that are inside the current selection.
Transparency
Some image file formats support an 'alpha channel', which allows you to specify the
opacity of every pixel in the image. In the alpha channel, a black pixel is regarded as
fully transparent, and a white pixel fully opaque. To edit this channel, make sure your
image supports it by going to Edit -> Properties... to set the image type. You can then
change the view between 'RGB' and 'Alpha' to show and edit either channel.
Passing the bitmap quickly to and from other applications
· Choose 'Copy' from the 'Edit' menu. This will put the current bitmap onto the
Windows clipboard, ready to be used by other applications.
· In your other application, paste the image (ideally 'paste to new') to begin editing it.
· When finished, select the image in the other application and use the 'copy' function in
that application to copy the new image to the clipboard.
· Back in DX Studio, choose 'Paste' and the bitmap will be updated to the new one.
Committing Changes
You can save the bitmap back into the editor at any time by choosing the 'Save' option
from the 'File' menu. Any changes will then be reflected in the editor.
Menus
DX Studio™ Editor
62
Introduction
4.2.9
Quick-Editing Sounds
4.2.9.1
Introduction
The quick-editor for sounds is designed to help you make simple changes to sounds and
preview the results in real-time.
You can still use 3rd party applications to perform advanced edits - just go to the Edit>Copy function to copy the bitmap to the clipboard, paste it into your sound editor,
perform the edits, copy it to the clipboard in your sound editor, and go to Edit->Paste to
embed the result back in the DX Studio document.
The sound editor will not commit any changes that you make until you choose the
'Save' option from the file menu. This saves the sound into the scene's resources, but
will not affect any external files that you may have loaded the sound from. In order to
extract a sound file from DX Studio you should use the 'Export' option from the file
menu.
Using the Sound Editor
4.2.9.2
Using the Sound Editor
The sound editor can be activated by double clicking any resource that is a sound file,
or by double clicking a sound in the 'Sounds' window.
Editing a Sound
Left click and drag over the sound waveform to select a region. Press the 'play' button
63
DX Studio™ Help
in the bottom right to preview your selected sound.
You can then edit the selected area using any of the functions in the 'Edit' or 'Tools'
menus.
For example, to perform a fade in over the selected region, go to the menu item Tools>Fade In and press the Play button to preview the results.
If you make a mistake, you can use the 'Undo' function to go back or the 'Redo'
function to re-apply any changes.
Committing Changes
You can save the sound back into the editor at any time by choosing the 'Save' option
from the 'File' menu. Any changes will then be reflected in the editor.
Menus
Introduction
4.2.10 Database Access
4.2.10.1 Introduction
In DX Studio™, full data access support is built in. This means that you can link to data
in either text files, SQL server databases, Access databases, or even data returned by a
URL.
At Director level, you have the ability to define data sets. Live data sets will need a
data source, which can be defined using the following steps...
· Find the 'Data Sources' window at director level (see the Window menu if you can't
find the window in the workspace).
· Add a new Data Source by clicking the 'Add Data Source' button.
· Point the data source to your database. See Data Source Properties for more
information.
· Find the 'Data Sets' window.
DX Studio™ Editor
64
· Add a new Data Set by click the 'Add Data Set' button. Configure the data set to be
linked to the data source you created in the previous steps. See Data Set Properties
for more information.
· That's it - the document now has data available that can be referenced in script or
used as a source for a chart.
Accessing data in script
For a single row of data, you can just access it using the following script:event onClick()
{
print("Data for column 'value' is: "+data.dataset_1.value);
print("Data for column 'name' is: "+data.dataset_1.name);
}
The column name in the database maps directly to the property name. You should
therefore avoid spaces in the column names in the database if you want to access that
column from script.
Note: In JavaScript, all data is returned as a string and so may need conversion for
different applications of the data.
For multiple rows of data, the rows are returned as an array using the 'rows' property of
the dataset...
event onClick()
{
var rows = data.dataset_1.rows; // Get the array of rows in a variable
for(var i=0;i<rows.length;i++)
{
print("Row "+i+" for column 'value' is: "+rows[i].value);
}
}
Writing back to the database
You can also execute SQL commands on the database or call stored procecures for
writing values back.
event onClick()
{
datasources.connection_1.executeSQL("INSERT INTO MyTable (Name,Sales) VALUES
('Chris',22)");
}
65
4.3
DX Studio™ Help
Reference Guide
This reference guide details the various menus, windows and functions available in DX
Studio™.
Note: Reference guide pages can be reached by hitting F1 when the dialog or
editor window that you need help on is active.
Menus - Menus used throughout the system.
Dialogs - Different dialog boxes that are used.
Script - Script language reference.
Introduction
4.3.1
Dialogs
The following windows and dialogs are available in the DX Studio™...
Director Level
Data Source Properties - Connection string configuration for a live database.
Data Set Properties - Configures data sets from the different data sources.
Generic Add Dialog - The form that is used to add any new type of object definition.
Director Properties - Options for the current DX Studio™ document.
2D Scene Editor Level
Add New Object - Options that can be set to map data between a scene and a live
database.
2D Scene Properties - Options relevant to the current 2D scene.
Tool Windows - The form that is used to add any new type of object definition.
3D Scene Editor Level
Add New Object - Options that can be set to map data between a scene and a live
database.
3D Scene Properties - Options relevant to the current 3D scene.
Effects - The form that is used to add any new type of object definition.
Light Properties - Options for the current DX Studio™ document.
Look At - Settings for the creation of a new empty scene.
Rotation Degrees - Windows used at director level.
Tool Windows - Windows used in 3D scene editing.
Quick Editors
Bitmap Editor - A simple tool for modifying bitmap size/type, and copying/pasting
between other applications.
Sound Editor - A fast and compact WAV file editor.
Introduction
DX Studio™ Editor
4.3.2
66
Menu Reference
The following menus are available in the DX Studio™...
Director Menu - Top level menu.
3D Scene Editor Menu - Menu found in the 3D editor window.
2D Scene Editor Menu - Menu found in the 2D editor window.
Introduction
4.3.3
Director
4.3.3.1
Menu Reference
The following menus are available in the DX Studio™ Director window...
File Menu
New - Clears the current director file and starts with a blank workspace.
Open - Open a DX Studio™ file (*.dxstudio).
Save - Save the current file.
Save As - Save the current file with a different filename
Recent Files - Open a file that has been recently opened before.
Exit - Close DX Studio™ Director. You will be prompted to save any changes that you
have made to your document first.
Edit Menu
Undo - Reverses the most recent change that you have made.
Redo - Re-applies the last change that was cancelled with an 'Undo'.
Edit Director Script - Allows you to edit the source code that defines the scene.
Properties - Opens a dialog that allows you to configure various settings for your
document. (See Director Properties for more information).
Tools Menu
Edit XML Source - Allows you to edit the source code that defines the scene. This is
an advanced feature that gives you full control over your data.
New Scene Wizard - Pops up a wizard that will help in adding a new scene.
Build EXE - Compiles the current document and the player into a single EXE file.
Build HTML - Generates a web page containing the HTML code needed to display the
document using the ActiveX player.
Build Image Sequence... - Pops up the Build Image Sequence dialog allowing you to
export the current document as a series of screen capture files.
Build AVI/GIF... - Pops up the Build AVI/GIF dialog allowing you to export the current
document as a animated movie in either video (AVI) or web compatible (GIF) formats.
Clear Cache - Removes any temporary files that have been cached to speed up
document previews.
Preview - Launches the player to preview the current document.
Plugins Menu
This menu contains any functions provided by plug-ins. For an up-to-date list of
67
DX Studio™ Help
available plugins, or for information on how to develop your own, please see the product
website.
Window Menu
Arrange Icons - Lays out minimized windows in order.
Cascade - Moves all windows to be in sequence moving down and right.
Tile Horizontal - Spreads windows over the width of the page.
Tile Vertical - Spreads windows over the height of the page
Default Layout - Moves all of the tool windows and bars back into their original
positions.
The numbered buttons show the available windows that can be switched to.
Help Menu
Contents - Brings up the contents page of the help system.
Index - Opens the index of the help system.
Search - Opens the search page of the help system.
On The Web - Internet based support pages, including 'Product Home' for more
information on DX Studio™ Director, 'Technical Support' for troubleshooting and advice,
and 'Check For Updates' to keep your product up to date.
Welcome - Brings up the original welcome splash screen.
Open Example - Brings up a list of available example files.
Plugin Information - Information on of all the currently installed plugins.
List All Installed Effects - Displays information on every plugin or built in effect
currently available.
About - Shows information on the current installed version of DX Studio™ Director. It
includes the individual/company the program has been licensed to, the license
agreement and serial number.
Check For Updates Now - Checks to see if a new version is available on the website.
Auto Check For Updates - When checked the check for updates web page will be
displayed on launch from time to time to make sure you've got the latest version.
Subscribe to Newsletter - Lets you add an email address to receive the DX Studio
Newsletter
Upgrade - Brings up the product upgrade page on the DX Studio site
Remove License - Downgrades the current product to Freeware so the license can be
used on another machine
Introduction
4.3.3.2
Director Windows
There are several windows in the top level editor that control the order and layering of
your scenes.
Scenes Window
DX Studio™ Editor
68
This window shows all of the scenes that you have in the document. Scenes are the
basis for all of the graphics in the document; the top level 'Director' is only concerned
with the order and position of scenes and not directly with any graphics itself.
Double click a scene to bring up the editor associated with it.
Layers Window
This window shows all of the layers in the document. A layer is a set of views and
modes, and by using multiple layers you can combine 2D and 3D graphics together.
The topmost layer in the list is drawn first (the background), and then each subsequent
layer is drawn over the top of the last.
Use the checkboxes to show/hide layers from being drawn in the editor.
Introduction
4.3.3.3
Build Image Sequence
This dialog lets you to export the current document as a series of screen captures.
69
DX Studio™ Help
Folder for output files - Click the Browse button to select where you want to place the
sequence of images.
Filename prefix - This is the common part of the filename that all output files will
share.
Numerical Places - This is the number of digits that will follow the prefix.
Start with index - The first image saved will be numbered with this value.
Sample filenames - An example of the first few files that would be created with the
current options.
Format - The image format of the output files.
Start Time (s) - The time, measured from the start of the document, from which
recording will begin.
Duration (s) - The length of time that recording will occur for.
Frames Per Second - The number of capture files that will be written for each second
recorded.
Total Files - The number of files that will be created given the current options.
Resize Images - If selected, each image will be saved at a different size to the natural
document size. The resize operation is filtered for a smoother result.
Store Current Settings In Document - If you click this button, the current settings
will be stored inside the document so that they are restored whenever you build an
image sequence using it.
Build - Launches the player and instructs it to build the sequence according to the
options set.
4.3.3.4
Build AVI/GIF
This dialog lets you to export the current document as an animated movie.
DX Studio™ Editor
70
Output file - Click the Browse button to select where you want to save the movie to.
Start Time (s) - The time, measured from the start of the document, from which
recording will begin.
Duration (s) - The length of time that recording will occur for.
Frames Per Second - The number of capture files that will be written for each second
recorded.
Format - The image format of the output files.
Resize Images - If selected, the movie will be saved at a different size to the natural
document size. The resize operation is filtered for a smoother result.
Max Colours (8-bit palette) - Animated GIFs are limited to a maximum 256 colours.
You should normally leave this setting as high as possible, but you may reduce the
number of colours in the output file down to just 2 if necessary.
Store Current Settings In Document - If you click this button, the current settings
will be stored inside the document so that they are restored whenever you build an
image sequence using it.
Build - Launches the player and instructs it to build the movie according to the options
set. For an AVI, you will be further prompted to select compression options when
recording begins.
4.3.3.5
Adding Definitions
The same process is used for adding definitions of any type. You can select where to
get the definition from using the following dialog...
71
DX Studio™ Help
Options
Load from library - The new definition is created by copying one from the library.
The library is a folder of building-block files, and is located in the DX Studio™ Director
install directory, under the sub-folder 'library'. Any files of the appropriate type found
in this folder will be listed here, and you can copy or remove your own files to/from this
folder.
Load from file - The new definition is created by copying one from a folder on your
hard drive. A file selection dialog will appear to let you select the appropriate file.
Load from current resources - A reference to a file that is already a resource is
added. This is useful if you want to create several references to a single definition.
Create a new empty definition - A new definition is created from scratch.
Introduction
4.3.3.6
Director Properties
The 'Director Properties' dialog is used to configure document-wide settings, such as the
size and shape of the display window.
General Tab
DX Studio™ Editor
72
Summary - Text description of the scene (optional). Summary information is shown
in the Windows Explorer as a tooltip.
Thumbnail - A thumbnail to be used to represent the scene. This can be one of the
auto-generated location_... thumbnails, or any other image that you have added to the
scene's resources.
Options Tab
Custom application title - In a standalone player, the application has a title that is
shown in the user's taskbar and the window's title bar. You can set this to be a custom
string here.
73
DX Studio™ Help
Install as a screensaver - This option affects standalone EXEs. When run it will ask
permission to install itself as a screensaver. It can then be selected as a standard
screensaver from the Windows Display Properties dialog box.
Max FPS - 3D applications can be demanding on available processor power. If your
application is happy with a particular lower frame rate, you should set it here. This
frees up time for other applications. FPS stands for 'frames per second'. Typical values
for film and television FPS are between 24 and 30.
Hide mouse cursor - This simply hides the system mouse cursor when it is inside the
application window.
Size Tab
Document Size - This is the default pixel size of the scene. In a 3D scene, this is
largely irrelevant as the scene can be displayed at any resolution without any resizing,
however the aspect ratio of the display may still be useful if you want to know where
the edges of the screen will lie. You can select any of the common preset sizes (e.g.
1024x768) to set the width and height automatically.
Show Window Frame - Enabling the window frame will draw a Windows application
title bar and border around the document. You can move a framed window by clicking
the title bar, as in any other Windows application. You can move a frameless window
by clicking and dragging from any inactive area inside the window.
Use Window Mask - If you don't have a window frame, you can use a black & white
image to define a mask. Where the image is white, the application window will appear
on the desktop. Where it's black, the desktop will show through.
Allow User Resize - If you have a framed window, this option sets whether the user
can resize it by dragging the window frame.
Set Window Size To Workspace Size - Will maximize the window over the user's
workspace (desktop minus the task bar).
Change Screen Resolution To Fit Document - Will attempt to change the screen
resolution to be the same as the document size. This gives a full-screen display.
Loading Tab
DX Studio™ Editor
74
Write loading progres... - This will dump performance related information on the
document load into the console of the player.
Customize loading screen - This enables the customization of the loading process
(only available in the Pro Edition of DX Studio).
Custom bacgkround - Changes the background of the loading screen to either a solid
color or an image scaled to fit the window.
Custom logo - This changes the logo (usually the DX Studio logo) to either not be
displayed, or to a custom logo image.
Show progress - Shows the progress bar as the document loads.
Network Tab
75
DX Studio™ Help
Link to other DX Studio documents over the network - This enables networking
features (Pro Edition only).
DX Studio Server IP Address - Set this value to point to your server, or use the
'Local Machine' button to set to your workstation for testing. The default port for a DX
Studio server is 9620, but this can be changed to any port so long as you set both the
server and the clients to use the same.
Group Identifier - All documents that want to communicate on the server must use
the same group identifier. If this is left blank, your document communicates in the
default group. Use the 'Generate New' button to create a new identifier that should be
copied and pasted between all documents that need to communicate with each other.
Document Identifier - You can identify a type of document in the group (e.g. a
control panel or interactive display) using this identifier. Press 'Generate New' to create
an indentifier for this document, which can then be used in scripts to send commands
to this document only.
Effects Tab
Effects can be added to a document in the same way as they are added to objects.
Please see Effects for more information.
Introduction
4.3.3.7
Data
4.3.3.7.1 Data Source Properties
This dialog lets you configure a live data source.
Text File Data Source
DX Studio™ Editor
76
By clicking the 'Text File' button, you can link to a text file containing comma
separated value data (CSV). The first line of the CSV file should contain the column
names (e.g. 'Name', 'Sales', etc.), and each subsequent line should contain the actual
data.
Any text files embedded as resources - this will look in the top level documents
resources for the text file.
Any text files embedded as resources - this will look in a particular directory WARNING: If you move the director file to another machine, the file may longer exist
at the specified path. You should therefore take great care when using absolute paths.
Test Connection - This will check to see if the specified text file directory exists.
NOTE: This does not actually locate individual text files, as these are defined later as
'tables'. It merely checks that the directory path is OK.
Database Data Source
77
DX Studio™ Help
Connection String - The OLEDB connection string that defines the address and
parameters needed to connect to the database. Your database manager should be able
to provide a suitable connection string, or alternatively you can use one of the string
builder wizards provided.
Connect to Access Database - This button pops up a browser to allow you to locate
the Access database file (.MDB extension). Once you have selected the file, the wizard
will provide the required connection string.
Connect to SQL Server - This button pops up the SQL Server Connection String
wizard that will help you to locate and connect to a SQL server database.
Test Connection - To check the connection string works, this button will attempt to
open the connection. If it works, the tables available in the database will be returned.
Otherwise, you will be notified of the error.
Web Page Data Source
DX Studio™ Editor
78
Folder URL - This is where you should supply a URL that defines the folder in which
your web pages that return data lie. For example, if a page called getdata.asp could be
found in http://www.worldweaver.com/data/ you should supply the folder URL 'http://
www.worldweaver.com/data/' here. For the purposes of web page data sources, the
file 'getdata.asp' is then used as the table.
Test Connection - As the full URL requires the table name, the test will append a
user supplied filename (eg. 'getdata.asp') to the folder path for testing.
Introduction
4.3.3.7.2 Data Set Properties
This dialog lets you configure a data set with user defined data or link it to a live data
source.
79
DX Studio™ Help
Name - A name for this data set that will be used to identify it.
Data Set Types...
Empty - a placeholder for a dataset that will be returned later.
User Data - the data is entered manually by clicking the 'Set Values...' button.
Auto-Fill - the data will be fetched using a SQL statement or stored procedure at the
given refresh interval.
Data Source - The data source that you want to get the table from.
Access Method - The type of access to the table. The default is a SELECT statement
that allows you to pick the table and define a sort if required. If you have a database
linked data source, you can also use a STORED PROCEDURE to get your data (these are
defined in the database itself).
Pick Table - This brings up a list of all the tables available in the data source. You
DX Studio™ Editor
80
simply select the one you want and click OK.
Sort results by a column - You can sort your table if required. Click this button to
choose the column that will be sorted on, and the order (ascending or descending) that
the rows will be sorted in.
Test - This will return the actual data in your table as defined by this form.
Introduction
4.3.4
Scene Editors
4.3.4.1
Common Windows
These windows are shared in both the 2D and 3D scene editors.
Sounds
This window lists all of the sounds that you have available in the scene. Sounds can be
triggered in script using the sounds collection.
Fonts
This window lists all of the fonts that you have defined in the scene. Fonts are used for
text objects. To add one, click 'Add Font', or to edit a font either use the 'Edit Font'
button or double click one.
For more information, please see the Fonts section.
81
4.3.4.2
DX Studio™ Help
Fonts
The fonts dialog is used to add or edit fonts in a scene.
Name - You can give your font an identifier here that you will use to refer to it
throughout the scene.
Resolution - In order to obtain the maximum drawing speed, fonts are converted into
bitmaps before being displayed. If you are going to be using a font only at a small size,
you can keep this resolution down and thus save memory.
By clicking a font sample in the window, you can change the font to any of those
installed on the system.
Tip: If you are going to be distributing the document to other PCs, they may not
have all the fonts that you have on your PC. To ensure that the font is displayed
correctly, you can right click on it in the Fonts window and choose to add the font as a
resource.
4.3.4.3
Edit Keyframes
This dialog allows you to animate an object over time. For user guide help on
animation please see the Introduction to Animation.
DX Studio™ Editor
82
Sequence - the sequence you are editing. You can add, remove and rename
sequences with the controls beside the drop down list.
Duration - the amount of time the sequence covers, from start to finish. You can
change this with the 'Set' button.
Snap To - the granularity of time that you want to deal with. The space between each
line in the timeline represents this period.
Auto play - this sequence will begin as soon as the object is created.
Loop - if set, the sequence will loop continuously.
The timeline window shows any keyframes that you have created as solid black
rectangles. You can right click on these to perform relevant actions.
The red line shows the current time that you are editing. If you modify the object in
the scene while this dialog is active, it will create keyframe data at the time where the
red line is.
If you want to see or edit what a keyframe contains, click inside the black rectangle to
select it.
The keyframe window has the following attributes...
Time - the selected time in the timeline window.
Property - a list of properties that have been keyframed at this time. You can select
one or more of these to configure tweening or remove them.
Tween In - how the keyframe relates to the previous keyframe.
Tween Out - how the keyframe relates to the next keyframe.
The tweening relation can be...
83
DX Studio™ Help
Jump - the data will only change on the exact keyframe (no tweening).
Linear - the data will move evenly between the two different values.
Stepped - the data will move more slowly at the start and end of the sequence.
Quad - the data will take into account 4 values at a time to produce a smooth motion
between all 4.
4.3.4.4
2D Scene Editor
4.3.4.4.1 Menu Reference
The following menus are available in the 2D scene editor's main window...
File Menu
Export Scene - Exports the scene to an external file.
Close Scene - Close the scene editor. The director file is updated automatically.
Edit Menu
Cut - Copies the selection to the clipboard, and removes it from the workspace.
Copy - Copies the selection to the clipboard without removing it from the workspace.
Paste - Copies contents of the clipboard into the current workspace.
Duplicate - Replicates the current selection.
Remove - Removes the current selection from the workspace.
Edit Scene Script - Allows you to edit the top level script in the scene.
Scene Properties - Opens a dialog that allows you to configure various settings for
your scene. (See 2D Scene Properties for more information).
View Menu
Zoom To Fit - While checked, this will automatically zoom the document to fit inside
the workspace window.
Zoom Level - Zooms the document to a fixed scale.
Insert Menu
Clicking any of these options will create an object in the scene of the selected type.
Format Menu
Make Group - If you have selected several objects, this option will put them into a
single group that you can move and transform as one object.
Break Group - If you have a group selected, this reverses the Make Group operation.
Order - Allows you to 'send to back' or 'bring to front' the selected objects in order to
change their drawing order.
Align - Aligns the selected objects along the specified side.
Space Evenly - Distributes the selected objects evenly.
Centre In Document - Aligns the selected objects so that they are in the middle of the
document in the specified direction.
DX Studio™ Editor
84
Tools Menu
Media Playlist - Add and remove audio/video files that will be played in order.
(For other options, see the Director Menus section)
Plugins Menu
homepage.
Window Menu
Default Layout - Resets the position and size of all of the property windows in the scene
editor.
Help Menu
Please see the Director Menus section.
Introduction
4.3.4.4.2 Object Properties
If you select an object in the world, the following properties become available...
85
DX Studio™ Help
Name - Identifier for the object that is unique within this scene.
Rename - Changes the identifier.
Definition - The identifier of the bitmap in the bitmap list to which this object refers.
Clicking the "Positoin,Rotation and Scale" button will bring up the following properties:Position - The X,Y position of the object from the top left of the document in pixels.
Size - If the object has a dynamic size, this represents the width and height in pixels.
Otherwise, the size will show the fixed width/height of the bitmap.
Scale - The horizontal/vertical scaling applied.
Rotation - The angle from horizontal of the object in degrees.
Origin - You can move the centre of rotation of a bitmap with these values.
The 'Sequences and Animations' button shows:Edit Keyframes - Brings up the Edit Keyframes animation window for this object.
The 'Script' button shows the script currently attached to the object, and the 'Visibility'
and 'Effects' buttons show the opacity and effects attached to the object respectively.
Other buttons that may appear depending on the object type include:Text - Allows you to edit the text string of a text object.
Web - Lets you configure a web browser object.
4.3.4.4.3 Add New Object
The Add New Object dialog lists all of the different types of object that you can add to
your scene. Click OK to add the selected object.
DX Studio™ Editor
86
Types
camera - 2D cameras are used to define the visible portion of the workspace.
text - Text can be either a single line or a block of text wrapped to a specified width.
effectpoint - This is a point on to which an effect can be applied. The point itself it
not drawn in the final document.
effectplane - This is a flat rectangular surface on to which an effect can be applied.
The plane itself is not drawn in the final document.
You can add an existing bitmap by dragging it from the 'Bitmaps' window into the
scene, or add a bitmap from a file using the 'Add Bitmap...' button.
Introduction
4.3.4.4.4 Scene Properties
The 2D Scene Properties dialog is used to configure the various attributes of a 2D
scene, such as background colour, grid settings, etc.
General Tab
Summary - Text description of the scene (optional).
scene's resources.
Size Tab
87
DX Studio™ Help
Document Size - 2D documents have a native pixel size. This sets the size of the
document in pixels
Document Scaling - If the owner document is of a different size to this scene, the
document will either need to be scaled to fit or positioned within the owner.
Background Tab
Background Type - Select the type of background that you want to use for the
scene.
none - the background is transparent.
solid - the background is a solid colour. Click the 'Colour' panel to change the
background colour.
image - the background is a bitmap. Click 'Browse' to select the file to use.
Grid Tab
DX Studio™ Editor
88
The grid can be used to help easily align objects when they are moved or rotated.
Snap to grid - Enables the grid and makes objects snap to even amounts of the grid
Spacing values.
Snap to edges - Objects 'stick' to the edges of other objects if they are within the
Range .
Origin X, Y - The offset of the snap grid - defaults to 0,0.
Spacing X, Y - Object coordinates will snap to the nearest spacing value above or
below their current position.
Edge Configuration Range - The distance away objects need be from each other
before the snap to edge occurs.
Effects Tab
Effects can be added to a scene in the same way as they are added to objects. Please
see Effects for more information.
Introduction
89
DX Studio™ Help
4.3.4.4.5 Windows
These windows are specific to the 2D scene editor. For other windows, please see the
Common Windows section.
Objects
The objects window shows all of the objects that are in the scene world. To help see
things more clearly, you can show/hide objects using the check box.
The up/down arrows can be used to change the order of objects in the scene. This will
change the order in which they are drawn, with objects at the bottom of the list being
drawn last.
Bitmaps
This window shows all of the bitmaps that you have defined for use in the scene. You
can drag a bitmap into the workspace to create another reference to it in the world.
DX Studio™ Editor
90
Introduction
4.3.4.5
3D Scene Editor
4.3.4.5.1 Menu Reference
The following menus are available in the 3D scene editor's main window...
File Menu
Export Scene - Exports the scene to an external file.
Close Scene - Close the scene editor. The director file is updated automatically.
Edit Menu
Duplicate - Replicates the current selection.
Remove - Removes the current selection from the workspace.
Edit Scene Script - Allows you to edit the top level script in the scene.
Scene Properties - Opens a dialog that allows you to configure various settings for
your scene. (See 3D Scene Properties for more information).
View Menu
Overview - Zooms out all windows to show the entire scene.
View Selection All - Zooms all windows to show the current selection.
Select All - Selects every top level object in the world.
Select None - Deselects every top level object in the world.
Lock Selection - Will not allow a selection change until this option is turned off.
Restrict Mouse To X - Only horizontal movement of the mouse will be used.
Restrict Mouse To Y - Only vertical movement of the mouse will be used.
Insert Menu
Clicking any of these options will create an object in the scene of the selected type.
Format Menu
Make Group - If you have selected several objects, this option will put them into a
single group that you can move and transform as one object.
Break Group - If you have a group selected, this reverses the Make Group operation.
Align - Aligns the selected objects along the specified side.
Space Evenly - Distributes the selected objects evenly.
Centre On Axis - Aligns the selected objects such that they are centred on the
specified axis.
Tools Menu
91
DX Studio™ Help
FishCube - Launches a fisheye to cubemap conversion utility. This lets you take 2
fisheye lens photographs and combine them into an environment map (cubemap).
Media Playlist - Add and remove audio/video files that will be played in order.
(For Clear Cache and Preview, see the Director Menus section)
Plugins Menu
available plugins, or for information on how to develop your own, please see the
Worldweaver website.
Window Menu
Objects - Shows or hides the objects that lists all of the objects in the scene.
Object Properties - Shows or hides the object properties window that allows editing of
the properties of the currently selected object.
Sounds - Shows or hides a list of all the sounds defined in a scene.
Fonts - Shows or hides a list of all the fonts defined in a scene.
Data - Shows or hides a list of all the data items defined in a scene.
Meshes - Shows or hides a list of all the meshes defined in a scene.
Help Menu
Please see the Director Menus section.
Introduction
4.3.4.5.2 Material Properties
The material properties dialog is used to edit the various attributes of a material, such
as it's colour, opacity and texture map.
DX Studio™ Editor
92
Name - Unique identifier of the material.
Ambient Colour - The colour of this material as lit by ambient light.
Diffuse Colour - The colour of this material as lit by diffuse light.
Specular Colour - The colour of this material as lit by specular light.
Power - The strength of specular light (between 0 and 1). This is determined by the
brightness of the Specular Colour .
Sharpness - The focus of the specular highlights on the material. A lower value
creates a softer effect.
Opacity - The 'solidness' of the material, where 100% is completely opaque, and 0%
is completely transparent.
Texture Map - An image file that is referenced by the texture coordinates in the
mesh. Note - if the mesh does not have texture coordinates, you cannot set a texture
map.
Add Bitmap - Add a new bitmap to be used as a texture map.
Edit Bitmap - Edit the selected texture map in the Bitmap Editor.
Copy Settings From - Lists all other materials in the scene - select one to copy it's
settings to this material.
Introduction
93
DX Studio™ Help
4.3.4.5.3 Add New Object
The Add Object menu lists all of the different types of object that you can add to your
scene...
Types
camera - Camera objects are used to view the scene in the player.
light - A light source can be a point (like a light bulb), directional (like daylight) or
spot (like a torch).
text - This is the simplest 3D text, where the text is flat but can be positioned and
rotated in 3D.
effectpoint - This is a point on to which an effect can be applied. The point itself it
effectplane - This is a flat rectangular surface on to which an effect can be applied.
The plane itself is not drawn in the final document.
effectcube - This is a cube inside which an effect can be applied. The cube itself is
chart - You can use charts to display data.
You can add an existing mesh by dragging it from the 'Meshes' window into the scene,
or add a mesh from a file using the 'Add Mesh...' button.
Introduction
4.3.4.5.4 Chart Settings
When you add a new chart or edit an existing one, the Chart properties will let you
configure the type and data source for your chart.
Chart Types
Bar/Column Chart
Standard Column - Columns are displayed across the X axis. If there is more
than one series, further columns are displayed behind the first set.
Stacked Column - Same as a standard column, except if there is more than one
series, the values are stacked on top of each other.
Stacked Column , Scaled 100% - Same as a stacked column, except all of the
columns are scaled to 100% of the available height.
Area Graph
Standard Area - Values are displayed as an area across the X axis. If there is
more than one series, further areas are displayed behind the first.
Stacked Area - Same as standard area, except if there is more than one series,
the values are stacked on top of each other.
Stacked Area , Scaled 100% - Same as stacked area, except all of the values
are scaled to 100% of the available height.
Line Graph
Standard Line - Values are displayed as a line across the X axis. If there is
more than one series, further lines are displayed behind the first.
Pie Chart
Standard Pie - Values are displayed as segments of a whole pie, representing
the total of all of the values.
DX Studio™ Editor
94
Data
Data - The chart gets its data from the data in the scene definition. Select which of
these to use in the drop down list.
Series Data Columns - A chart should have at least one series of data to plot. Click
Add Series to add one.
Column for Value Labels - If each value has a label (such as 'name'), you should
select the label column here. This allows column and pie charts to label the axes
correctly.
Series Column - This selects the column that should be used as the value to be
plotted in the selected series.
Colour Cycle - This defines how the colours alternate with each value. Click a colour
cell to edit the colour.
Preset - You can use a predefined preset colour cycle by selecting one from this list
box.
Colours - You can set the number of colours in the cycle by pressing the up/down
arrows.
Background Grid
This section lets you turn on/off the background grid, and set the colours for the
background, major and minor grid lines.
Category (X) Axis and Value (Y) Axis
Show Labels - Determines whether labels are drawn along the axis.
Font - The font to be used to draw the labels. You define these fonts for the scene in
the 'Fonts' window.
Size - The font size the labels are to be drawn at.
Colour - The colour of the labels.
Manual Range - Allows you to fix the range of the axis to the following...
From, To - The minimum and maximum values that the axis can display
Major Every, Minor Every - The values that will be drawn as major and minor axis
lines.
Bar/Column Chart Specific
Settings that are specific to a bar chart, such as the size of the bars.
Introduction
4.3.4.5.5 Effects
This property sheet can be used to add effects to an object, scene or document. For
user-guide help on effects, please see the Introduction to Effects.
Functions
Depending on the type of object/scene/document you have selected, a range of
appropriate effects will be available.
95
DX Studio™ Help
Add Effect - Adds an effect to the object.
Edit - Click this button to configure the selected effect.
You can change the order in which effects are applied with the Up and Down arrow
buttons, or remove an effect with the delete button.
Introduction
4.3.4.5.6 Light Properties
This property sheet lets you configure a light's type, colour, range, and falloff
parameters.
DX Studio™ Editor
96
Type - The type of light that is emitted:directional - the simplest type of light that has just a direction (e.g. sunlight).
point - a light that has position, but emits equally in all directions (e.g. a light
bulb).
spot - a light that has position and direction (e.g. a torch).
Colour - The colour of the light. A pure black light has no effect, whereas a pure white
light is the brightest.
Range - The maximum distance over which the light has effect.
Attenuation - How the power of the light diminishes over the range.
Cone - For 'spot' lights only. The cone determines the angle of the beam from the
light (from narrow to wide).
97
DX Studio™ Help
Introduction
4.3.4.5.7 Look At
The 'Look At' dialog is used to point an object at another object in the scene. This relies
on the object having it's 'forward' direction in the +Z direction (as a camera does). If
the object faces the other way, the 'Flip' command should be used in the object's
properties to get the correct direction.
Settings
Look At Object - Click to select the object that you want to 'look at'. This will set the
position automatically.
Look At Position - You can manually enter a position in world coordinates to look at
here.
'Up' Direction - Unit vector defining which way appears to be 'up' in the viewport. By
default +Y is the up direction for all cameras in the scene, but you can use any
direction. Click +Y to keep the viewport in the standard orientation.
Introduction
4.3.4.5.8 Rotation Degrees
This dialog can be used to specify a rotation in degrees around each of the X,Y,Z axes in
sequence. This is simpler than calculating a quaternion (X,Y,W,Z) rotation.
DX Studio™ Editor
98
Parameters
X-axis - The rotation around the X-axis (left to right) in degrees.
Y-axis - The rotation around the Y-axis (bottom to top) in degrees.
Z-axis - The rotation around the Z-axis (front to back) in degrees.
Relative to current rotation - If selected, this rotation will be applied to the existing
rotation. Otherwise, the rotation will be applied from a zero rotation and the current
rotation will be ignored.
Introduction
4.3.4.5.9 Scene Properties
The 3D Scene Properties dialog is used to configure the various attributes of a 3D
scene, such as background colour, grid settings, etc.
General Tab
99
DX Studio™ Help
Summary - Text description of the scene (optional).
scene's resources.
Size Tab
Document Size - This is the default pixel size of the scene. In a 3D scene, this is
largely irrelevant as the scene can be displayed at any resolution without any resizing,
however the aspect ratio of the display may still be useful if you want to know where
DX Studio™ Editor
100
the edges of the screen will lie. You can click any of the preset size buttons (e.g.
1024x768) to set the width and height automatically.
Display Distance Range - Objects are not drawn if they are nearer than the 'Near '
value to the camera, nor if they are further away than the 'Far' value from the camera.
You will get the best results if you set these to accurately represent the scale of your
scene.
Background Tab
Background Type - Select the type of background that you want to use for the
scene.
none - the background is transparent.
solid - the background is a solid colour. Click the 'Colour' panel to change the
background colour.
image - the background is a bitmap. Click 'Browse' to select the file to use.
cubemap - the background is a cube map. This requires a special DDS (DirectX
Surface) or 6 image JPEG strip file to represent the 6 inside faces of the cube.
Ambient Light - This is the light that will be applied to all objects in the scene
regardless of any other light settings. Typical colours are black (no ambient light), dark
grey (small amount of ambient light) or white (all objects lit at full brightness).
Background Sound - This sound will be played in a continuous loop in the background
while this scene is displayed.
Grid Tab
101
DX Studio™ Help
The grid can be used to help easily align objects when they are moved or rotated.
Snap to grid - Enables the grid and makes objects snap to even amounts of the grid
Spacing values.
Snap to edges - Objects 'stick' to the edges of other objects if they are within the
Range .
Snap rotations - When objects are rotated, the amount they can be rotated by in any
direction is snapped to the Rotation Snap Angle .
Origin X, Y, Z - The centre of the snap grid - defaults to 0,0,0.
Spacing X, Y, Z - Object coordinates will snap to the nearest spacing value above or
below their current position.
Rotation Snap - The Angle defines the smallest unit of rotation that an object can be
rotated by.
Effects Tab
Effects can be added to a scene in the same way as they are added to objects.
see Effects for more information.
Please
Introduction
4.3.4.5.10 Sound Usage
Sounds can either be simple (as most will be) or positioned. A positioned sound is
attached to an object in the 3D world via script, and depending on the position and
orientation of the camera, will sound as if it's coming from the object.
DX Studio™ Editor
102
Types
Simple sound - This is the default type of sound. It can be used anywhere except as
a sound attached to an object, for which you need a positioned sound.
Positioned sound - A sound that is played in 3D space (i.e. attached to a 3D
objects). The result is such that if the object to which the sound is attached is to the
left of the camera, the sound will come from the left speaker, etc.
Introduction
4.3.4.5.11 Windows
These windows are specific to the 3D scene editor. For other windows, please see the
Common Windows section.
Objects
Meshes
103
DX Studio™ Help
Introduction
4.3.5
Bitmap Editor
4.3.5.1
Menus
DX Studio™ Editor
104
File
Save - Update the changes to the sound by saving the file back into the scene.
Export - Save the current workspace to an external file.
Close - Close the editor window.
Edit
Copy - Copies the current bitmap to the clipboard without removing it from the
workspace.
Crop - Trims the sound so that only the selection remains.
Properties - Views the properties of the current bitmap.
View
RGB Channel - Displays the normal colour channel of the bitmap.
Alpha Channel - Displays the transparency channel of the bitmap. White pixels are
solid, black pixels are transparent.
Tiled - Repeats the bitmap horizontally and vertically to preview how it would wrap in
3D.
Zoom In/Out/Percentage - Sets the zoom level of the edit window.
Select
All - Causes the entire image to be selected.
None - Deselects everything.
Inverse - Selects every pixel not in the current selection.
Rectangle - A tool that will select a rectangle of pixels.
Ellipse - A tool that will select an ellipse of pixels.
Magic - A tool that will select all pixels adjacent and similar to the clicked pixel - the
similarity threshold can be set by 'Magic Settings'.
Magic Settings - Brings up a dialog that allows you to set the tolerance (similarity
threshold) to be used by the magic tool. A lower value for this means that selected
pixels must be a closer match in colour.
Mapping (for 3D scenes only)
If the bitmap is used as a texture map, and faces using this texture map are selected in
the 3D scene editor, this menu will allow you to adjust the mapping coordinates of the
3D object.
Tools
Invert - Inverts the colours in the current bitmap, producing a negative.
Brightness/Contrast - Allows modification of the brightness and contrast of the
image in percentage terms.
Adjust RGB - Allows increase/decrease of red, green and blue components separately.
105
DX Studio™ Help
Fill - Fills the current selection with either a solid colour or a gradient.
Invert - Produces the negative of the current image.
Mono - Converts the image to be either solid black or solid white pixels.
Paintbrush - A simple paintbrush tool for drawing onto the image. The settings for
this can be changed in the 'Brush' window.
Plugins
This menu contains any functions provided by plugins. For an up-to-date list of
website.
Introduction
4.3.6
Sound Editor
4.3.6.1
Menus
File
Save - Updates the changes to the sound by saving the file back into the scene.
Export - Saves the current workspace to an external file.
Close - Closes the editor window.
Edit
DX Studio™ Editor
106
Crop - Trims the sound so that only the selection remains
Remove - Removes the selection from the sound.
Select All - Selects the entire sound.
Properties - Views the properties of the current sound.
Control
Play All - Plays the entire sound.
Play Selection - Plays only the current selection of sound.
Stop - Stops playing the sound.
Set Cursor Start/End - Moves the cursor to the start or end of the sound.
Tools
Silence - Mutes the area currently selected.
Normalize - Adjusts the volume of the selection such that the highest peak in the
data is also the maximum sample value.
Fade In - Fades the sound in over the duration of the selection.
Fade Out - Fades the sound out over the duration of the selection.
Volume - Increase/decrease the volume of the sound data (increasing may produce
clipping).
Plugins
website.
Introduction
4.3.7
Script Reference
Script in DX Studio is based on ECMAScript (otherwise known as JavaScript).
Note this is a summary of the scripting language for reference purposes. For help on
how to write and use script, please see the user guide section.
Keywords
- defines a general function
- defines a variable
if ... else ... - for conditional blocks
print(...) - writes a string to the player console
do, for, while, switch case, etc. - all standard JavaScript keywords are supported.
function
var
Events
Here is a list of the different types of events that can be handled.
Semantics
107
DX Studio™ Help
/* */ blocks or // lines for comments
operators +, -, *, /, !
comparisons ==, !=, <, >, <=, >=
group with brackets ( )
increment, decrement ++, -Library Functions
Math - a useful library of common mathematical functions
Vector - represents a 1,2 or 3 co-ordinate vector (x,y,z).
Rotation - represents a single axis (x) or quaternion (x,y,z,w) based rotation.
Particle - a very basic object that can be used in particle systems. Can be created with
the 'new' keyword.
system - system level functions and variables
objects - object access and properties
sounds - start/stop sounds
keys - contains the state of all keyboard keys
data - database manipulation
textures - access document textures
scenes - access document scenes
layers - access document layers
network - network communications functions
shell - owner application communication
Example - Object Script
/*
example1 - moves the object 10 along the x axis when clicked
*/
function onClick()
{
object.pos.x += 10;
if (object.pos.x>100)
{
object.pos.x -= 100;
}
}
Introduction
4.3.7.1
Color
A basic type used to represent a color that can be created with the 'new' keyword.
Properties
r
Floating point value between 0 and 1 representing the red component.
g
Floating point value between 0 and 1 representing the green component.
b
Floating point value between 0 and 1 representing the blue component.
a
Floating point value between 0 and 1 representing the alpha component (may
be ignored for some uses).
Examples
DX Studio™ Editor
108
You can declare a Color either by it's # code...
new Color("#rrggbb")
var col = new Color("#ff0000"); // col is a Color type, set to bright red.
...or by it's floating point components...
new Color(r,g,b)
var col = new Color(1.0,0.0,0.0); // again col is a Color type, set to bright red.
You can also initialize an alpha value with....
new Color(r,g,b,a)
var transcol = new Color(1.0,0.0,0.0,0.5);
4.3.7.2
// transcol is bright red, but 50% transparent.
data
Access data within the current scene.
Syntax
data.<data item name>[<rowindex>].<columnname>
Where the <rowindex> selects a particular row in the data, and <columnname> selects
a particular column. You can omit the row specification, and it will default to the first
row in the table.
Examples
data.companysales.value // returns the value in the 'value' column from the default first row
in the companysales data item.
data.companysales[5].description // refers to the 6th row (indexed from 0 don't forget),
returning the 'description' column value for that row.
function setStringToName()
{
object.text=data.mypeople[0].surname;
}
Remarks
See Also
Script Reference
4.3.7.3
Events
Events are just functions with reserved names that are called when different things
happen. So to handle an event, just create a function in script with one of the following
names...
109
DX Studio™ Help
Events
onClick
Called every time the object is clicked. [Applies to object script only]
onUpdate
Called every time a frame is displayed.
onInit
Called once when the document is first initialized.
onMouseDown
Called when a mouse button is pressed.
onMouseMove
Called when the mouse is moved.
onMouseUp
Called when a mouse button is released.
onMouseWheel Called when the mouse wheel is scrolled up or down. The amount is
stored as a floating point number in the event structure as
'mouseWheelDelta'. +1.0 is a single notch up, and -1.0 is a notch
down.
onHoverBegin
Called when the mouse moves from not over to being over an object.
[Applies to object script only]
onHoverEnd
Called when the mouse moves from being over an object to not being.
[Applies to object script only]
onKeyChange
Called when a keyboard key is pressed or released.
onShow
Special event that is called whenever a keyframe is displayed.
[Applies to keyframe scripts only]
onCollision
Called when two objects that have the notifyCollision flag set on them
collide. As this applies to object script only, the parameter passed to
the event is the id of the other object hit.
onCollisionBegi Same as the onCollision event, but only called once when the objects
n
first collide.
onCollisionEnd Same as the onCollision event, but only called once when the objects
finish colliding.
Event Structure
Every event also has the option to receive an event structure that describes the detail
of the event. To get this, just add a variable in the function parenthesis, by convention
say calling this 'e'. For example...
function onMouseWheel(e) // note the 'e' now in the definition
{
print("Mouse wheel changed by: "+e.mouseWheelDelta);
}
The event structure contains the following members...
srcElement
A string containing the id of the object that raised the event (if
any).
clientX
X position of the mouse when the event occured (integer).
clientY
Y position of the mouse when the event occured (integer).
button
The mouse button(s) involved in the event (integer).
DX Studio™ Editor
110
ctrlKey
Boolean value, true if the Control key was down when the event
occured.
altKey
Boolean value, true if the Alt key was down when the event
occured.
shiftKey
Boolean value, true if the Shift key was down when the event
occured.
mouseWheelDelta
Amount the mouse wheel changed for the event - a floating
point number, -1 per notch down or +1 per notch up.
rawDX
Raw amount the mouse was moved by in the X direction
(integer).
rawDY
Raw amount the mouse was moved by in the Y direction
(integer).
Examples
To handle the onClick event, edit the script for an object and enter the following code...
function onClick()
{
print("You clicked!");
}
4.3.7.4
Face
Allows manipulation of a single face in a mesh.
Methods
flip()
Reverses the order of v1 and v2 so that the face is flipped over.
Properties
v0, v1, v2
Indices of the 3 vertices used to make up the face.
materialIndex
An index of which material on this submesh to use for this face.
Examples
function onClick()
{
var verts=object.subgroups.Box.vertexGetArray(); // get all the vertices in the Box
subgroup
verts[15].pos.x+=10; // move a vertex +10 along the X axis
object.subgroups.Box.vertexSetArray(verts); // save changes
var faces=object.subgroups.Box.faceGetArray(); // get all the faces in the Box
subgroup
faces[0].materialIndex=1-faces[0].materialIndex; // swap material index of face
between 1 and 0
object.subgroups.Box.faceSetArray(faces); // save changes
}
Remarks
111
DX Studio™ Help
Changes to the mesh are not written until the faceSetArray function is called.
The materialIndex property can only reference materials set up on the subgroup. To
add one, click the subgroup in the objects window, and add a material in the Object
Properties -> Materials panel.
See Also
System
4.3.7.5
File
Returned by the system.file.openRead(filename) or system.file.openWrite(filename)
functions.
Properties
length
The byte length of the file returned as an integer.
Methods
close()
Must be called when you're finished with the file.
readStringArray()
Returns an array of strings, each representing a line in a
text file.
writeStringArray(stringarray) Writes all of the strings in the string array to the file,
putting each string on a new line.
readByte()
Returns an integer in the range 0-255 read as the next
raw byte in the file.
writeByte(byte)
Writes an integer in the range 0-255 to the file as raw
data.
Examples
This example shows reading and writing an array of strings to/from a file on disk.
(Here it's assumed c:\temp exists)
function onClick()
{
// write directory file list out to text file
var outbuf = system.file.getFiles("c:\\temp\\*.*",false);
var file=system.file.openWrite("c:\\mylist.txt");
file.writeStringArray(outbuf);
file.close();
// read files in from text file
var file=system.file.openRead("c:\\mylist.txt");
var inbuf=file.readStringArray();
file.close();
print("Reading file...");
for(var i=0;i<inbuf.length;i++)
{
print("Read: "+inbuf[i]);
DX Studio™ Editor
112
}
}
See Also
Script Reference
4.3.7.6
layers
Access director level layers from anywhere in the document.
Syntax
layers.<layer name>.<property>
For a description of the properties and methods of a layer, please see the layer script
reference.
Examples
layers.layer_1.x = 100;
Remarks
See Also
Script Reference
4.3.7.7
layer
Allows the run-time manipulation of a layer in a DX Studio document.
Methods
moveUp()
moves the layer up the layers list at runtime - layers further up the list
are drawn first
moveDown()
moves the layer down the layers list at runtime - layers further down
the list are drawn last
Properties
visible
gets or sets the runtime visibility of the layer
index
gets or sets the runtime index of the layer in the layers list. Changing
the index will change the order in which the layer is drawn. The indices
of other layers will change to accommodate changing this index.
scene
gets or sets the scene id (string) of the scene to be displayed in this
layer.
camera
gets or sets the camera id (string) of the camera in the layer's scene to
be used.
Examples
113
DX Studio™ Help
layers.layer1.camera="camera_2"; // set the layer's camera to camera_2
Remarks
See Also
Script Reference
4.3.7.8
Keyframe
A keyframe is a class that represents a single keyframe in a Sequence for an object,
created using a createKeyframe method.
Methods
setPropertyPos(vpos, [, tween])
Adds a position property at the Vector
position vpos. You can optionally specify the
tween as a string, where possible values are
"jump", "linear","stepped", or "quad".
setPropertyRot(rot. [, tween])
Adds a rotation property of the Rotation rot.
You can optionally specify the tween as a
string, where possible values are "jump",
"linear", "stepped", or "quad".
setPropertyScale(vscale [, tween])
Adds a scale property at the given time (in
seconds) of the Vector scale vscale. You can
optionally specify the tween as a string,
where possible values are "jump", "linear",
"stepped", or "quad".
Properties
time
Gets or sets a floating point value representing the time of this keyframe.
Examples
var seq=object.createSequence("test",1); // create a sequence called 'test' on the current
object
var mykeyframe = seq.createKeyframe(0); // create a keyframe at time 0
mykeyframe.setPropertyPos(new Vector(100,100,0)); // set the pos for this keyframe
mykeyframe = seq.createKeyframe(1); // create a keyframe at time 1
mykeyframe.setPropertyPos(new Vector(100,100,100)); // set the pos for this keyframe
Remarks
An example of run-time sequence creation can be found in the 'puzzlegame' demo.
See Also
Script Reference
DX Studio™ Editor
4.3.7.9
114
keys
Collection of true/false values representing the state of each keyboard key. A full list of
valid key names can be found here.
Syntax
keys.<key name>
All possible values of <key name> are listed in the 'Collection Members' box in the
source editor.
Examples
function onKeyChanged()
{
if (keys.space)
{
sounds.youpressedspace.play();
}
}
Remarks
See Also
Key Name Reference
Script Reference
4.3.7.10 objects
The objects collection contains all of the objects in the current scene. 'objects.<object
name>.<...>' can access any object from the scene, or you can access the current
object with just object.<...>'
Syntax
objects.<object name>.<...>
For a description of the properties and methods of an object, please see the object
script reference.
Examples
objects.camera_1.pos.x=200; // sets the x position of the camera_1 object to 200.
See Also
object
system
4.3.7.11 object
Every object has properties for position, rotation, scale, etc. You can access and modify
these attributes in script.
115
DX Studio™ Help
Objects can be accessed via any of the following methods:object.<property> - property of the object the script is attached to.
objects.<object name>.<property> - property of the named object in the same scene
as the script.
scenes.<scene name>.objects.<object name>.<property> - reference to a particular
object in a particular scene from any script.
Properties
pos
Current position of the object (Vector type)
rot
Current rotation of the object (Rotation type)
scale
Current scale of the object (Vector type)
timer
A float value (in seconds) that increases with time
passing. Can also be set to reset the timer.
animation
A string that represents the id of the current x file
animation.
sequence
A string that represents the id of the current keyframe
sequence.
text
For a text object, this represents the text string.
textFont
The font id used by a text object (font must be defined in
the scene).
textSize
The size of the text in scene units.
textAlign
The alignment of the text, a string value of either
"left","right", or "centre".
visible
Set to true if the object is to be drawn, false to hide it.
posVelocity
Delta position of the object per second (Vector type)
rotVelocity
Delta rotation of the object per second (Rotation type)
rotvelocityOver
A float determining how long (in seconds) the object takes
to cover the rotation described in rotVelocity. This is
usually 1.0, but if you want an object to rotate more
quickly than 90 degrees per second, you should instead
reduce this value rather than make rotVelocity any bigger.
A rotation is a snapshot not a scalar value, so a full 360
rotation is back to the start, which would not then know
which way to turn.
opacity
A float value between 0 and 1, where 0 is invisible and 1
is solid.
fov
Floating point value that represents the vertical field of
view of a camera in radians. The default value is
0.78539.
subgroups
A collection of all the Subgroup objects inside a mesh
object.
effects
A collection of all the effects applied to an object.
DX Studio™ Editor
116
posConstrain
The id (string) of an object which is to be used to
constrain the position of this object. The object to be
used must have a mesh.
posConstrainMargin
The smallest distance this object can get to a face on the
constraining object (always should be greater than zero).
keyMoveSpeed
Sets the speed in units per second for movement via the
keyboard (float)
keyMoveSoften
Sets the amount to soften keyboard movement
acceleration (float).
posWorld
Position of the object in world coordinates (not relative to
the parent).
radiusWorld
Radius of a bounding sphere fully containing the object in
world coordinates.
boundingBoxMin
Returns a Vector specifying the smallest world x,y,z
position that the object occupies.
boundingBoxMax
Returns a Vector specifying the largest world x,y,z position
that the object occupies.
wireframe
Boolean value that if true draws this object in wireframe
mode (default is false).
showBounds
Boolean value that if true draws the bounding box around
the object (default is false).
shadowDynamicCast
Boolean property determining when the object casts
dynamic shadows on to itself or other objects.
shadowDynamicShow
Boolean property determining when the object shows
dynamic shadows on it's surface.
color
Used in objects with a color, such as a light.
light
If the object is of type 'light', then this has further subproperties; the sub-property 'type' is a string determining
the type of light source, one of "point", "spot" or
"directional". Booleans useLighting, useShadows, usePRT
enable/disable the light for those different uses. Floats
phi, theta, range, falloff, attenuation0/1/2 determine the
charactistics of the light.
physicsSolid
Set to true/false to enable/disable this object from
obstructing other objects.
physicsReact
Set to true/false to enable/disable this object from
reacting to solid objects.
physicsGravity
Set to true/false to enable/disable gravity.
117
DX Studio™ Help
camera
If the object is a camera, then this has the subproperties:- type (the type of camera in a string,
"projection" or "ortho"), fovVertical (represents the
vertical field of view of the projection camera in degrees the default value is 45.0), fovHorizontal (represents the
horizontal field of view in degrees), orthoZoom (a float
determining the zoom of an ortho camera),
lodDistanceScale (a float that is multiplied by every
distance in a LOD detail calculation, so if you set it to zero
every object will be drawn at maximum detail). You can
also configure the listener properties for 3D sound listenerMPU, listenerRolloff and listenerDoppler.
animationTransitionPeriod
Floating point value determining how quickly one
animation changes to another. Defaults to 0.0 meaning
the animation changes instantly. 1.0 would be over 1
second, etc.
animationSpeed
Floating point value that is a multiplier for the animation
playbackspeed. Defaults to 1.0, 2.0 would be double
speed, etc.
faceCamera
Set to true and the object will rotate itself automatically to
face the camera.
faceCameraLockVertical
If faceCamera is true, this boolean value determines
whether the object can rotate freely or is locked to the Y
(vertical) axis.
animationTimer
Position of the current animation in seconds.
offsetPos
Usually used in conjunction with 'attach'. A Vector that
will offset the position of the mesh before applying the
attachment transformations.
offsetRot
Usually used in conjunction with 'attach'. A Rotation that
will offset the rotation of the mesh before applying the
offsetScale
Usually used in conjunction with 'attach'. A Vector that
will offset the scale of the mesh before applying the
lookAt
A string id of an object for this object to look at. Set to an
empty string to stop looking.
animationNext
Sets the animation that will be played when the current
one completes (string id). This is set to the same as
'animation' every time 'animation' is set, so you should set
animationNext after. e.g. object.animation='Walk'; object.
animationNext='Idle';
notifyCollision
If set to true, the object will report collisions with other
objects (onNotifyCollision event) with notifyCollision set to
true. By default notifyCollisionCheckFaces will also be
true, so a face by face comparison will be performed (you
can improve the perfomance of this by using a separate
low poly mesh for physics).
DX Studio™ Editor
118
notifyCollisionCheckFaces
If set to true (and the object it's colliding with has this set
to true) a face by face check will be performed.
Otherwise, only the bounding box intersection check will
be done. The default value is true.
emitter
A collection of properties if the object is of type 'emitter'.
path
A collection of properties to control the object's movement
along a path.
Methods
createSequence("<sequence
name>")
Returns an empty keyframe Sequence object
that will overwrite any existing sequence of the
same name. Use this function to create run-time
keyframe sequences.
click()
Simulates a mouse click on the object by calling
the onClick() function (if present).
animationGetArray()
Returns a list of ids of mesh animations available
for this object.
sequenceGetArray()
Returns a list of ids of sequences available for
this object.
subgroupGetArray()
Returns a list of ids of all the subgroups inside a
mesh object.
canSee(objectid, [aspect, fov])
Used on camera objects. Pass a string identifier
of an object, and it will return true if the camera
can see the object. By default the function will
assume the document's aspect ratio for the
camera and pickup the fov from the camera
itself. You can override these by optionally
passing two floats for the aspect ratio and fov to
use.
shapeAddLine(vectorFrom, vectorTo, Draws a line (relative to the position of the
col)
object) between the two Vectors in the given
Color.
e.g. object.addShapeLine(new Vector(0,0,0), new
Vector(100,0,0), new Color('#ff0000'));
shapeAddTriangle(v0, v1, v2, col,
fill)
Draws a triangle (relative to the position of the
object) between the three triangle Vectors in the
given Color. If the optional fill paramter is set to
true, the shape is solid.
shapeAddRectangle(vtopleft,
Draws a rectangle (relative to the position of the
vtopright, vbottomleft, vbottomright, object) between the four corner Vectors in the
col, fill)
given Color. If the optional fill paramter is set to
true, the shape is solid.
shapeRemoveAll()
Removes all shapes currently being drawn on the
object.
119
DX Studio™ Help
animationMergeAdd(id)
Merges the given animation (by animation
identifier string 'id') with the current animation
on the object.
animationMergeRemove(id)
Removes the given animation from being merged
with the current animation on the object.
animationMergeSetPos(id,prop,play) Moves the animation (already added with
animationMergeAdd) to the given floating point
proportion along it's length 'prop' (between 0 and
1). If a boolean 'play' is set to true, it will play
from this point, otherwise it will stay at this
position.
animationGetDuration(id)
Returns the duration of the given animation in
seconds.
moveToGroup(groupid)
Changes the group that the object is in to the
one with the given string id. Set to an empty
string to have no group.
attach(objid,subgroupid,attachpos,
attachrot,attachscale)
Attaches the pos/rot/scale of an object to
another (with optional subgroup - set to an
empty string to be the top level). The optional
booleans attachpos/attachrot/attachscale define
which properties are passed through (defaults to
all true).
attachedObjectGetArray()
Returns an Array of Object types listing all
objects currently attached to this one.
Accessing script functions/variables
You can also call functions defined in object script, or read/write variables. Just prefix
the function/variable with 'script.' to access...
script.<variable>
script.<function>
Examples
object.pos.x=100; // sets the x position of the object this script is written in to 100.
objects.camera_1.pos.x=200; // sets the x position of the camera_1 object to 200.
object.script.myTestFunction(); // calls the function defined in the current object.
print("Object health is "+object.script.health); // Prints the value of the variable 'health'
defined in an object.
See Also
system
4.3.7.12 Particle
A particle is a very basic object that can be used in particle systems.
DX Studio™ Editor
120
It has the following properties:pos
current position of the particle
posVelocity
position velocity of the particle - the amount the position should be
adjusted by every second.
destroy()
call this method to destroy the particle immediately
visibleDir
A Vector used with visibleFOV to determine a direction from which the
particle must be viewed from to be visible.
visibleFOV
A floating point value that defaults to zero (always visible). If greater
than zero, this determines the angle of visibility about the Vector
visibleDir in degrees (360 degrees is visible all around, 180 degrees is a
hemisphere, etc).
attach(objid,
subgroupid,
attachpos,
attachrot)
Attaches the pos/rot/scale of this particle to an object (with optional
subgroup - set to an empty string to be the top level). The optional
booleans attachpos/attachrot define which properties from the target
are used (defaults to true).
visible
Simple boolean property that defaults to true. Even if this is true,
visibleFOV could make the particle invisible.
Examples
// Simple particle creation example
// This code should be attached to a moving object, and 'particle_1' should be defined in the
'Particles' window.
var period=0.1; // create a particle every 0.1 of a second
function onUpdate()
{
if (object.timer>period)
{
object.timer-=period;
var p=new Particle("particle_1"); // create a new Particle object based on the
'particle_1' definition.
p.pos=object.pos;
// set the particle's position to be the same as this
object's.
p.posVelocity=new Vector(0,-10,0); // the particle will fly downwards as it
fades away.
}
}
See Also
Script Reference
4.3.7.13 Material
A material determines the color characteristics of a surface used in a mesh. It is a
basic type that can be created with the 'new' keyword.
Properties
ambient
A Color type representing the ambient light component of the
material.
121
DX Studio™ Help
diffuse
A Color type representing the diffuse light component of the
material.
specular
A Color type representing the specular light component of the
material.
emissive
A Color type representing the emissive light component of the
material.
specularSharpness A floating point value determining how the specular light is
reflected.
textureMap
A string that names the bitmap file in the resources to be used for
the texture map. Set to "" if no texture map.
Methods
loadFromFile(filename)
Sets the material up from the given .dxmaterial file.
This may be a file on disk or a URL.
Examples
meshes.car.materials.paintwork.diffuse = new Color("#ff0000");
car to red.
// sets the paintwork of the
meshes.car.materials.paintwork.loadFromFile("http://www.dxstudio.com/examples/grass.
dxmaterial.zip"); // loads the material from a dxmaterial file on the web server (with zip
extension as otherwise server may not serve file)
See Also
Script Reference
4.3.7.14 Math
A collection of useful mathematical functions.
Methods
abs(value)
Calculates the absolute value or magnitude of a number.
acos(value)
Returns the arc cosine of the value provided in radians.
asin(value)
Returns the arc sine of the value provided in radians.
atan(value)
Returns the arc tangent of the value provided in radians.
atan2(x,y)
Returns the arc tangent of y/x, using the signs of the arguments to
compute the quadrant of the return value.
ceil(value)
Returns the smallest integer no less than the value.
cos(value)
Returns the cosine of the value, where the value is an angle expressed
in radians.
exp(value)
Returns e (2.7182818) raised to the 'value'th power.
floor(value)
Returns the largest integer no greater than the value.
log(value)
Returns the natural logarithm of the value.
DX Studio™ Editor
122
max(value1,
value2,
value3...)
Returns the maximum value of any number of arguments.
min(value1,
value2,
value3...)
Returns the minimum value of any number of arguments.
pow(x,y)
Returns x raised to the y power.
random
([seed])
Returns a random floating point number between 0 and 1.
round(value)
Returns the value rounded to the nearest integer.
sin(valuue)
Returns the sine of the value, where the value is an angle expressed in
radians.
sqrt(value)
Returns the square root of the value.
tan(value)
Returns the tangent of the value, where the value is an angle
expressed in radians.
Examples
var mynumber=-10;
var mag=Math.abs(mynumber);
print("Magnitude of "+mynumber+" is "+mag);
...which prints... "Magnitude of -10 is 10"
See Also
Script Reference
4.3.7.15 media
Controls the media playback component.
Methods
play()
Plays each track of media in the playlist in turn. If paused, this will
resume playback.
stop()
Stops playing, and rewinds to the start of the track.
pause()
Pauses playback of the current media.
forward()
Advances to the start of the next track.
back()
Moves to the start of the previous track.
playFile(filename) Plays any media file from a disk file or URL immediately.
Properties
track
Moves to the start of the specified track number.
Examples
system.media.play();
123
DX Studio™ Help
system.media.track=5;
Remarks
If you haven't set your media to 'auto-play', you will need to make sure you call
'system.media.play()' at some point in your script.
See Also
System
4.3.7.16 meshes
You can access all the mesh definitions for a scene using this collection.
Syntax
meshes.<mesh id>.<...>
For a description of the properties and methods of a mesh, please see the mesh script
reference.
Examples
meshes.cube.materials.facemat.ambient = new Color(1.0,1.0,1.0);
in 'cube' mesh.
// set the facemat material
See Also
Script Reference
4.3.7.17 mesh
A mesh is defined in a scene and can be referred to any number of times by world
objects.
Properties
materials
A collection of all the named materials in the mesh file.
lodOrigin
A Vector that determines the origin for LOD calculations.
Methods
loadFromFile(filename) Changes the mesh by loading a new file from disk or from a
URL.
materialsGetArray()
Returns all the material ids as an Array of Material objects.
Examples
meshes.cube.materials.facemat.ambient = new Color(1.0,1.0,1.0);
in 'cube' mesh.
// set the facemat material
meshes.cube.loadFromFile("c:\\demo\\mymesh.x"); // Changes the mesh file of the 'cube' mesh to
a new one from disk.
DX Studio™ Editor
124
meshes.cube.loadFromFile("http://www.dxstudio.com/examples/wooden_cart.dxmesh.zip"); //
Changes the mesh file of the 'cube' mesh to a new one from a URL
See Also
Script Reference
4.3.7.18 network
A collection of network control functions. You must enable networking in the DX Studio
document properties to use these functions. The groupId and documentId properties
are also set in the document properties dialog. The instanceId property is created by
the DX Studio Player every time the player is run.
Methods
send(commandstring)
Send a command to all network clients in the same group.
getNetworkSet(idstring)
Returns a NetworkSet object for the given identifier (GUID
string).
Properties
groupId
Returns the group identifier (GUID string) for the current
document.
documentId
Returns the document identifier (GUID string) for the
current document.
instanceId
Returns the instance identifier (GUID string) for the
current document.
Examples
network.send("system.exit();"); // all documents in the group will exit immediately
print("This player can be uniquely identified by this string: "+network.instanceId);
Remarks
GUID strings are just strings that are guaranteed to be globally unique. This helps to
identify a document, group or individual player that you want to communicate with.
See Also
Script Reference
4.3.7.19 NetworkSet
A NetworkSet is a class that represents an individual or group on the network. You
obtain a NetworkSet using the network class.
Methods
send(commandstring)
Sends the script in 'commandstring' to
everyone that's in this NetworkSet.
125
DX Studio™ Help
sendScreenCapture()
Sends a screenshot of the current player
window to all members of this NetworkSet.
getDocumentArray()
Returns an array of NetworkSet classes that
represent all of the different documents
found in this group. Will only work if the
NetworkSet has a group identifier.
getInstanceArray()
Returns an array of NetworkSet classes that
represent all of the different instances found
in this NetworkSet. Will work if the current
NetworkSet is a group or document identifier.
Properties
id
Returns the identifier (GUID string) for this NetworkSet.
Examples
var nsgroup = network.getNetworkSet(network.groupId); // Get a NetworkSet for this current
document's group identifier.
var docs = nsgroup.getDocumentArray(); // Get an Array of NetworkSets for all different
documents in this group.
var instances = nsgroup.getInstanceArray(); // Get an Array of NetworkSets for all diferrent
player instances in this group.
print("This group contains "+docs.length+" different documents, and "+instances.length+"
different player instances.");
nsgroup.send("print('hello!');"); // tell everyone in the group to print 'hello!' in the
console.
for(var i=0;i<instances.length;i++)
{
var ns = network.getNetworkSet(instances[i].id); // Get a NetworkSet to communicate
with this individual player
ns.send("print('I am player "+(i+1)+" of "+instances.length+"!')"); // Tell the player
to say their index in this list
}
Remarks
An example of network usage can be found in the 'net_cabinet.dxstudio' and
'net_cabinet_controller' example files.
See Also
Script Reference
4.3.7.20 Rotation
A basic type used to represent a rotation that can be created with the 'new' keyword.
The constructor can be called without parameters, passed the x,y,z,w quaternion values
of the rotation, or alternatively you can construct with a Rotation with 3 degree values
representing rotations about the x,y,z axes in order. You can also pass another
Rotation object as a contructor to copy the initial values from.
Methods
DX Studio™ Editor
126
normalize()
Normalizes the quaternion rotation (scales such that the
components total 1)
reset()
Resets the value to the identity rotation (0,0,0,1).
rotateAxis(vaxis,
angle)
Applies a rotation of 'angle' radians around the axis described
by the Vector 'vaxis'.
Properties
x
Floating point value representing the x component of the rotation.
y
Floating point value representing the y component of the rotation.
z
Floating point value representing the z component of the rotation.
w
Floating point value representing the w component of the rotation.
Examples
var myRot = new Rotation(); // create a variable called myRot representing the identity
rotation.
var myRot1 = new Rotation(0.0,0.0,0.0,1.0); // create a variable called myRot representing the
specified quaternion.
var myRot2 = new Rotation(10.0,5.0,0); // create a Rotation that represents a 10 degree
rotation about the x-axis, followed by a 5 degree rotation about the y-axis.
var myRot3 = new Rotation(myRot2); // create a Rotation with x,y,z,w values copied from
myRot2.
object.rot.rotateAxis(new Vector(0.0,1.0,0.0), 45.0); // Rotate the current object 45 degrees
about the axis (0,1,0).
Remarks
A 3D rotation is mathematically a 'Quaternion'. They allow the storage of rotations
without any of the problems associated with Euler angles.
See Also
Script Reference
4.3.7.21 scenes
The scenes collection contains all of the scenes in the DX Studio document. 'scenes.
<scene name>.<...>' can access any scene from the entire document, or you can
access the current scene with just 'scene.<...>'
Syntax
scenes.<scene name>.<...>
For a description of the properties and methods of a scene, please see the scene script
reference.
Examples
scenes.myscene1.script.openDoor(); // calls the 'openDoor' function in the scene 'myscene1'.
scenes.scene_2.objects.ship.script.Explode(); // calls the 'Explode' function of the 'ship'
127
DX Studio™ Help
object in 'scene_2'.
Remarks
See Also
Scene
Script Reference
4.3.7.22 scene
A scene in script is directly related to a scene in a DX Studio document.
Properties
script
Provides access to all of the functions and variables in the
scene.
media
Controls the media player for the scene.
objects
Access objects in the scene.
sounds
Access sounds in the scene.
textures
Access texture maps in the scene.
meshes
Access meshes in the scene.
timer
A floating point timer for the scene.
ambientLightColor
A Color value for the ambient light in a 3D scene.
backgroundColor
A Color value representing a solid background.
backgroundImage
The name of the resource to be used as a background
image.
backgroundEnvironment
The name of the environment map to be used as a
background in a 3D scene.
fogType
The type of fog used in a 3D scene. Can be none, linear,
exponential or exponential2.
fogColor
The color of the fog in a 3D scene. This will override any
other background.
fogStart
The distance at which the fog starts having an effect (linear
fog).
fogEnd
The distance at which the fog becomes solid (linear fog).
fogDensity
The factor by which fog becomes more dense (exponential
fog).
wireframe
Boolean value that if true draws the scene in wireframe
mode (default is false).
lighting
Boolean value that if false disables any lighting in the
scene (default is true).
mouseX
Scene coordinates of the current mouse X position.
mouseY
Scene coordinates of the current mouse Y position.
DX Studio™ Editor
128
lastHitInfo
Collection of properties of the last ray cast (either by
mouse or function). Full details here.
zNear
Sets the near Z clip plane (float) - this should be as high as
possible without losing any near to camera objects.
zFar
Sets the far Z clip plane (float) - this should be as close to
the near plane as possible without losing any distant
objects.
alphaRef
An integer value between 0 and 255 that determines the
cutoff value used as a reference alpha testing. A low value
will cause very transparent edges to be drawn which might
block the z-buffer, a higher value will be smoother but may
lose some texture around the edge.
Methods
objectAdd(id,type)
Adds an object called 'id' and sets the 'type'
to be the identifier of the mesh/bitmap/
object used as a definition. e.g. var myobj =
scene.ObjectAdd("clock_1","clock");
objectRemove(id)
Removes the object with the given id from
the world.
objectGetArray()
Returns an Array of Object types
representing all of the objects in the world
for this scene.
objectsCollide(id1,id2,[tolerancefactor],
[checkfaces])
Returns true if the object with identifier id1
collides with the object with identifier id2.
You can also optionally set a floating point
tolerancefactor (which defaults to 1.0), such
that if you set it to 0.9, the objects could be
10% closer before the collision was
triggered. A final optional boolean can be
used to actually check the faces for
intersection if the first basic test is passed set to true to enable this.
mouseOverPlane(planepoint,
planenormal)
Returns true if the mouse is over the given
3D plane. The plane is defined by 2
Vectors, a point on the plane and the
normal to the plane.
mousePlanePos(planepoint, planenormal) Returns a Vector giving the current 3D
position of the mouse over the given 3D
plane. The plane is defined by 2 Vectors, a
point on the plane and the normal to the
plane.
129
DX Studio™ Help
rotationDeltaFromScreenDelta(screendx,
screendy,factor)
Returns a Rotation that represents the
change in rotation represented by a
movement in screen coordinates given the
current scene's camera. Combine this with
the current rotation of an object, and feed in
the change in x,y mouse coordinates to get
interactive object manipulation.
getObjectFromRay(rayfrom,raydir,range) Returns an object class of the nearest world
object hit by a ray from Vector 'rayfrom' in
the director of Vector 'raydir' with an
optional maximum range. Returns null if no
object found.
meshAdd(objectdefid, filename)
Adds a new Mesh definition to the scene.
(Use objectAdd to create an object and pass
the objectdefid as the type).
meshRemove(objectdefid)
Removes the Mesh definition from the
scene.
Examples
scene.media.track=2; // goes to track 2 in the media player list for the current scene.
scenes.myscene1.script.openDoor(); // calls the 'openDoor' function in the scene 'myscene1'.
scenes.scene_2.objects.ship.script.Explode(); // calls the 'Explode' function of the 'ship'
object in 'scene_2'.
function onInit()
{
var objs=scene.objectGetArray(); // get an Array of all the objects in the world for
this scene.
print(objs.length+" objects in the scene.");
for(var i=0;i<objs.length;i++)
{
print(objs[i].id+" ("+objs[i].type+")"); // Prints out all the object ids along
with their type.
}
}
Remarks
See Also
Script Reference
4.3.7.23 Sequence
A sequences is a class that represents a keyframe sequence for an object, created using
the createSequence method.
Methods
DX Studio™ Editor
130
createPositionKeyframe(time, vpos [,
tween])
Creates a position Keyframe at the given
time (in seconds) at the Vector position vpos.
You can optionally specify the tween as a
string, where possible values are "jump",
"linear","stepped", or "quad". The return
value from the function is the Keyframe that
has been created.
createRotationKeyframe(time, rot [,
tween])
Creates a rotation Keyframe at the given
time (in seconds) given the Rotation rot. You
can optionally specify the tween as a string,
"stepped", or "quad". The return value from
the function is the Keyframe that has been
created.
createScaleKeyframe(time, vscale [,
tween])
Creates a scale Keyframe at the given time
(in seconds) of the Vector scale vscale. You
can optionally specify the tween as a string,
"stepped", or "quad". The return value from
the function is the Keyframe that has been
created.
createKeyframe(time)
Creates an empty Keyframe at the given time
(in seconds). The return value from the
function is the new empty Keyframe.
Properties
duratio Gets or sets a floating point value representing the length of the sequence in
n
seconds.
Examples
function onclick()
{
var seq=object.createSequence("test1", 1); // create a new sequence called "test1"
that's 1 second long.
seq.createPositionKeyframe(0, new Vector(100,100,0), "stepped"); // add a position
keyframe at 0s.
seq.createPositionKeyframe(1, new Vector(100,100,100), "stepped"); // add a position
keyframe at 1s.
object.sequence="test1"; // activate the sequence.
}
Remarks
An example of run-time sequence creation can be found in the 'puzzlegame' demo.
See Also
Script Reference
131
DX Studio™ Help
4.3.7.24 shell
Functions that talk to the application that hosts the player as an ActiveX control, or if
running as an EXE this will send commands to the Windows shell.
Methods
send(commandstring)
Send a string to the application. This will be received as an
event called 'Receive' in the host application.
execute(commandStrin Sends the 'commandString' to the Windows shell with
g, paramString,
optional parameters in paramString. For security
commandIsProgId)
reasons, this function is not available when running
in a web browser. If you set commandIsProgId to
true, you can launch a utility by it's ProgID, e.g.
'WMP.DVD' with parameter 'play' would play a DVD in
Windows Media Player.
Examples
shell.send("hello from a DX Studio document!");
shell.execute("notepad.exe"); // launches notepad application (if running as an EXE)
shell.execute("http://www.dxstudio.com/"); // launches a browser at www.dxstudio.com (if
running as an EXE)
shell.execute("notepad.exe","d:\\mydoc.txt"); // launches notepad application and opens d:\
\mydoc.txt
shell.execute("c:\\"); // opens a file explorer for the c:\ folder
shell.execute("WMP.DVD","play",true); // plays a DVD in media player
Remarks
See Also
Script Reference
4.3.7.24.1 send
Send a script command to the application hosting the player as an ActiveX control.
Syntax
shell.send("<your own command or information string>")
Examples
shell.send("mainmenu"); // sends the string 'mainmenu' to the host application.
Remarks
See Also
Script Reference
DX Studio™ Editor
132
4.3.7.25 sounds
Controls sounds within the current scene.
Syntax
sounds.<sound name>.<...>
For a description of the properties and methods of a sound, please see the sound script
reference.
Examples
sounds.ping.play(); // plays the sound called 'ping'.
See Also
Script Reference
4.3.7.26 sound
Controls the playback of a sound.
Syntax
play()
Plays the current sound once.
playLooped()
Plays the current sound in an endless loop.
stop()
Stops the sound from playing.
setVolume(level)
Sets the volume of the sound, where level is between 0
(silent) and 1 (full).
setPan(pos)
Sets the left/right pan of the sound, where pos is
between -1 (left) and 1 (right).
setWorldPosition(posvector,
[velvector])
Sets the 3D position of a sound (must be set to
position mode by right clicking in the Sounds window).
You can also optionally pass another Vector to give the
current velocity at this position.
frequency
Integer value that determines the frequency (Hz) the
sound is played at (useful to modify this for engine
notes). If coming from a floating point value, use
Math.floor(fVal) to get a usable integer for this
function.
Examples
sounds.ping.play(); // plays the sound called 'ping'.
Remarks
If the sound has been set as 'positioned' when played from an object, the sound will be
played in 3D space according to the position of the object relative to the current
camera.
133
DX Studio™ Help
See Also
Script Reference
4.3.7.27 Subgroup
Allows manipulation of a single face in a mesh.
Methods
vertexGetArray()
Returns an array of Vertex objects that can be
manipulated.
faceGetArray()
Returns an array of Face objects that can be
manipulated.
vertexSetArray(vertexarray)
Writes the given array of Vertex objects back into the
mesh.
faceSetArray(facearray)
Wrties the given array of Face objects back into the
mesh.
attachedObjectGetArray()
Returns an Array of Object types listing all objects
currently attached to this particular subgroup.
Properties
id
Gets or sets the name of the subgroup (string).
visible
Gets or sets whether the subgroup is visible (boolean).
materials
A collection of all the Materials
pos
Local Vector position of the subgroup for this object.
rot
Local Rotation of the subgroup for this object.
scale
Local Vector scale of the subgroup for this object.
posMesh
A read-only Vector that determines the actual position
of the subgroup within the whole Mesh.
posWorld
A read-only Vector that determines the current true
world position of the subgroup.
Examples
// in this example, the following script is attached to a newly created box object...
function onClick()
{
subgroup
subgroup
between 1 and 0
}
DX Studio™ Editor
134
See Also
System
4.3.7.28 system
System level functions and variables.
Methods
exit()
Terminate the application.
restart()
Reloads the document and runs from the beginning
again.
load(filename)
Loads and displays the specified document.
fullScreenToggle()
Switches between full screen and windowed playback.
saveScreenCapture(filename,
[format], [postprefix])
Saves a screenshot of the current player window to a
JPG, PNG, BMP or DDS file on disk. The function will
determine the type from the filename, or you can
optionally pass a string of "jpg","png","dds" or "bmp"
as a second parameter to force it to save a certain
type.
If instead of a filename you pass a URL (such as
http://www.dxstudio.com/examples/showscreenshot.
aspx) the screenshot will be sent as a HTTP POST to
the given URL. By default the image will be sent as
the value 'screenshot', but you can override this by
setting the optional 'postprefix' string. The last
parameter sent in this string is always the image, so
valid postprefixes would be for example
"myscreenshotjpg=" or "client=dave&screenshot=".
The image file will be in base64, so you'll need to
convert it to bytes before saving. You may also need
to replace spaces ' ' with the plus sign '+' in the data
before conversion. Some sample code can be found
at http://www.dxstudio.com/examples/
showscreenshot.aspx.
Any data returned from a URL post will be saved and
can be retrieved as a string using
getLastPostResponse().
The function returns true if successful.
postToURL(url, postdata)
This function takes a string url for the target to post
to, and a string postdata that contains & separated
name=value pairs. e.g. myval=1&otherval=test
The function returns true if successful.
getLastPostResponse()
Returns a string containing the complete last response
received from a post to a web server.
135
DX Studio™ Help
callDLL(dllFilename,
functionName, [params]...)
Calls any function in any DLL given by the DLL file
name and function name. Additional simple
parameters may also be passed, with their types being
automatically converted to/from JavaScript. This is an
obvious security risk and so will prompt the user the
first time a DLL level function is requested during the
execution of a document.
Properties
script
Access director level script variables.
media
Control media playback.
window
Control the position/size of the playback window.
folders
Strings for the disk locations of the various system folders.
contextMenu
Functions to enable/disable, add to or clear the player's context
menu.
backgroundCol
Gets or sets the Color for the background of the player window
(defaults to black).
timer
A system wide user timer. Set to zero and it will increase in
seconds as time passes.
timerDelta
A constant for each update pass representing the amount of time
that has elapsed since the last update in seconds.
ui
User interface related properties, such as the mouse position or
object that the 'mouse look' controls.
debug
Get/set whether the debug window is visible or not (true/false)
fullScreenMode
Get/set whether the player is running in full screen mode (true/
false)
file
File system related functions.
clock
Call the update() method to set the following properties to the
current time: day, month, year, hour, minute, second, dayOfWeek.
Months are numbered 1-12 and the day of the week returns 0 for
Sunday, 1 for Monday, etc.
Remarks
System wide variables need to be declared in the director level script, outside of any
function. They can then be accessed from any script using the above notation.
See Also
Script Reference
4.3.7.28.1 contextMenu
Functions to enable/disable, add to or clear the player's context menu.
Properties
DX Studio™ Editor
136
add(name,script,enabledConditionScript, Adds a new user item to the context menu.
iconFileName, iconConditionScript)
The 'name' is what's displayed in the menu,
and the 'script' is the script to execute when
the item is selected. You can also
(optionally) pass 'enabledConditionScript' that
will only enable the menu item if the script
evaluates to boolean 'true'. The
'iconFileName' is the name of an image
resource at director level (or a full path to it's
location on disk), and the
'iconConditionScript' will only show the icon if
it evaluates to boolean 'true'. Images should
be 16x16 pixels.
clear()
Removes all user items from the context
menu.
enabled
A boolean value to set wheter the context
menu is available.
active
Returns true if the context menu is currently
being shown. Can also be set to manually
show/hide the menu.
Examples
system.contextMenu.enabled=true;
system.contextMenu.clear();
system.contextMenu.add("Say Hello","print('hello!');"); //Sends 'hello!' to the console if you
choose this menu item.
system.contextMenu.add("Say Hello","print('hello!');","(system.timer>2.0)","speaker.png","");
//Only enable the command if 2 seconds have passed. Also show 'speaker.png' as an icon.
Remarks
To customize the appearance of other items in the menu, use the Properties dialog at
director level.
See Also
System
4.3.7.28.2 exit
Causes the application to close immediately.
Syntax
system.exit()
Examples
event click()
{
system.exit();
}
// closes the application when this object is clicked.
137
DX Studio™ Help
Remarks
If the application is running in a standalone window, this function will close the window
and terminate the application. If the player is embedded in a browser or other
document, this command is ignored.
See Also
System
4.3.7.28.3 file
gFunctions involving the filing system.
Methods
getFiles(filespec,recurse)
Returns an array of strings, each string is the full
filename of every file matching the given filespec
string. An example filespec string would be c:\
\myfolder\\*.jpg. Set 'recurse' to true to search all
subfolders too.
openRead(filename)
Opens the given filename and returns a File object to
access it. The File object uses properties/methods:length, close(), readStringArray(), readByteArray().
Always call close() when you're finished with the file.
openWrite(filename)
Opens the given filename and returns a File object to
access it. The File object uses properties/methods:close(), writeStringArray(stringarray), writeByteArray
(). Always call close() when you're finished with the
file.
exists(filename)
Returns true if the given file exists.
delete(filename)
Deletes the file and returns true if successful.
rename(filename,newfilename) Returns true if the given file is renamed to the new
filename.
copy(filename,newfilename)
Returns true if the given file is successfully copied to
the new filename.
move(filename,newfilename)
Returns true if the given file is successfully moved to
the new filename.
Examples
function onInit()
{
var files = system.file.getFiles("c:\\myfolder\\*.jpg",true);
print("Found "+files.length+" files!");
for(var i=0;i<files.length;i++)
{
print("File "+i+": "+files[i]);
}
}
Remarks
DX Studio™ Editor
138
See Also
System
4.3.7.28.4 load
Loads a new document from the specified filename or url.
Syntax
system.load(filename)
system.load(url)
Examples
function onClick
{
system.load("c:\dxstudio\examples\puzzlegame.dxstudio"); // if you click this object,
the puzzlegame document will be loaded.
}
function onClick
{
system.load("http://www.dxstudio.com/examples/example1.dxstudio"); // if you click
this object, the example1 document will be streamed from the specified URL.
}
Remarks
The new document will be loaded in place of the current one.
See Also
System
4.3.7.28.5 registry
Functions to read/write values from the Windows registry.
Properties
subKey
For security, all variables are stored in a special DX Studio
key, but you can specify any string as a sub key. To be
absolutely sure that your application doesn't interfere with
another, you can use your document's GUID as a subkey.
readValue(name)
Reads an entry from the registry called 'name'. The returned
type will match that of the variable used to write the value.
writeValue(name,value)
Makes an entry in the registry called 'name' and sets it to
'value'. Values can be strings or numbers.
Examples
function onInit()
139
DX Studio™ Help
{
system.registry.writeValue("testval",11.73);
var test=system.registry.readValue("testval");
print("Value read from registry: "+test);
}
Remarks
The full registry key to your document values is...
HKEY_LOCAL_MACHINE\SOFTWARE\Worldweaver\DX Studio\DocVars\[subKey]
See Also
System
4.3.7.28.6 restart
Restarts the entire document from the beginning.
Syntax
system.restart()
Example
function onClick
{
system.restart(); // if you click this object, the document will start again from the
beginning.
}
Remarks
All script variables are also re-initialised.
See Also
System
4.3.7.28.7 script
Gets or sets a director level script variable, or calls a director script function.
Syntax
system.script.<variable name>
system.script.<function name>(<function params>)
Examples
In director script...
var mycounter=0; // declares a variable 'mycounter'.
function testFunc() // a test function
{
print("testing...");
}
DX Studio™ Editor
140
In script on an object in a scene...
function onInit()
{
system.script.mycounter=0; // set the system variable 'mycounter' to 0.
}
function onClick()
{
system.script.mycounter++;
system.script.testFunc();
}
// increment the system variable 'mycounter'.
// calls the test function
function onUpdate()
{
if (system.script.mycounter>0)
{
// do something if the system variable 'mycounter' is greater than 0.
}
}
Remarks
System wide variables need to be declared in the director level script, outside of any
function. They can then be accessed from any script using the above notation.
See Also
System
4.3.7.28.8 window
Gets or sets dimensions of the display window (in a standalone windowed playback
enviornment).
Properties
width
Gets or sets the width of the player window.
height
Gets or sets the height of the player window.
x
Gets or sets the x position of the player window.
y
Gets or sets the y position of the player window.
Examples
system.window.width=640;
system.window.height=480;
Remarks
All coordinates are in pixels, relative to the top left of the desktop.
See Also
System
141
DX Studio™ Help
4.3.7.28.9 ui
User interface related functions.
Properties / Methods
mouse
Has properties x, y and button that represent the current
position of the mouse relative to the top left of the player
window, and which mouse button(s) are down. Also returns
hitInfo which gives details of the actual subgroup/face the
mouse is over for a mesh. Methods show() and hide() will
show/hide the cursor.
joystick
Has properties x, y, z and button that represent the current
position of the joystick where 0.0,0.0,0.0 is the joystick in
the centre. Values range from -1.0 to 1.0 along each axis.
As joysticks often do not return to the absolute centre, a
property zeroRange can be set to determine how far a
joystick must move along an axis before it is registered.
The default is 0.2. Advanced properties rx,ry,rz, pov0,
pov1, pov2, pov3 and slider0, slider1 are also available.
mouseLookObject
Gets or sets the object that will be controlled by dragging
the right mouse button in the player window.
keyboardMoveObject
Gets or sets the object that will be controlled by pressing
the cursor keys.
paletteDialog(initialcol)
Brings up a modal color selection box (pauses script
execution). Returns a Color value if OK is pressed, or null if
cancelled. Pass a Color as a parameter to give a default.
Examples
print("Mouse x position is: "+system.ui.mouse.x);
system.ui.mouseLookObject=scenes.scene_1.objects.camera_1; // Control the camera in scene_1
with the mouse.
// script for a camera object in a 3D scene
var speed=10.0;
function onUpdate()
{
if (system.ui.mouse.button==1)
{
object.pos.x+=system.timerDelta*speed; // move along the x axis, accounting for
the frame update rate.
}
}
// Check which buttons are down
function onUpdate()
{
for(var buttonIndex=0;buttonIndex<31;buttonIndex++)
{
if (system.ui.joystick.button & Math.pow(2,buttonIndex))
{
print("Button "+buttonIndex+" is down");
}
}
}
DX Studio™ Editor
142
Remarks
All mouse x/y coordinates are in pixels.
See Also
System
4.3.7.28.9.1 hitInfo
Returns more detailed information on the subgroup and face of a mesh that have been
hit.
Properties
hit
Returns true if there was a hit.
object
Returns an Object class for the object hit.
subgroup
Returns a Subgroup class for the subgroup hit.
faceIndex
Returns the zero based index for the face hit.
faceU
The proportion across the face (between 0 and 1)
faceV
The proportion across the face (between 0 and 1)
posWorld
The real world position hit (Vector).
posLocal
The position of the hit relative to the position of the object
(Vector).
distance
The distance the hit occurred at (float).
mySubgroup
If this is a collision between two objects, this returns the
Subgroup class for the subgroup of the current object, or
null if no subgroup/not a mesh.
myFaceIndex
If this is a collision between two objects, this returns the
zero based face index of the face hit in the subgroup of the
current object.
Examples
function onClick()
{
print("You clicked face "+system.ui.mouse.hitInfo.faceIndex);
}
Remarks
The 'object' and 'subgroup' properties return classes so to get a sub-property (for
example the subgroup id) first check for null, then look up the Id property.
See Also
System
143
DX Studio™ Help
4.3.7.29 textures
Access texture maps within the current scene.
Syntax
textures.find("<texture filename>") - returns a Texture object for the given texture
filename
textures.load("<texture filename>") - preloads the texture file for later use
textures.unload("<texture filename>") - forceably removes the texture file from video
memory
Examples
textures.find("grass.png").reload(); //reloads grass.png from its original file
textures.load("dog.png"); // preloads the dog.png bitmap for later use
textures.unload("dog.png"); // kicks the dog.png texture out of video memory
Remarks
The 'find' method must be used as a filename may contain punctuation or spaces which
would otherwise break the language grammar.
See Also
Texture
Script Reference
4.3.7.30 Texture
A texture represents any bitmap based resource.
Properties
filename
A read only string that specifies the filename the current texture
was loaded from.
Methods
loadFromFile(filename)
Replaces any references to this texture map with a new
texture from the given image file. This may be a file on
disk or a URL.
Examples
textures.find("mychair.jpg").loadFromFile("http://www.dxstudio.com/examples/latestshot.jpg");
See Also
Script Reference
DX Studio™ Editor
144
4.3.7.31 Vector
A basic type used to represent a 2D/3D position that can be created with the 'new'
keyword.
You can construct a Vector by passing 3 floating point coordinates, or copy the values
from another Vector object.
Properties
x
Floating point value representing the x component of the vector.
y
Floating point value representing the y component of the vector.
z
Floating point value representing the z component of the vector.
Examples
var myPos = new Vector(100,200,300); // create a Vector called myPos representing the position
x=100, y=200, z=300.
var myPos1 = new Vector(25.7,11.3,19.9);
var myPos2 = new Vector(myPos1); // creates a new Vector with values copied from the first
vector
See Also
Script Reference
4.3.7.32 Vertex
Allows manipulation of a single vertex in a mesh.
Methods
normalize()
Scales the normal of the vertex to be of unit length.
Properties
pos
A Vector describing the x,y,z position of the vertex.
normal
A Vector describing the x,y,z direction of the normal to the surface at this
vertex.
texture
A Vector describing the texture coordinates at this vertex.
Example
function onClick()
{
subgroup
subgroup
between 1 and 0
145
DX Studio™ Help
}
Remarks
Changes to the mesh are not written until the vertexSetArray function is called.
See Also
System
4.3.7.33 RotationMath
A collection of useful mathematical functions for manipulation of rotations.
Methods
combine(rotation, rotation)
Combines (i.e. multiplies) two rotations together to
produce a new rotation.
fromUpVectorAndAngle
(upvector, angle)
Returns a Rotation given an 'up' Vector and a floating
point angle to finally rotate about that Vector in
degrees.
fromForwardVectorAndAngle
(fwdvector, angle)
Returns a Rotation given a Vector pointing 'forwards'
and a floating point angle to finally rotate around that
Vector in degrees.
orbitRotHeading(anglearound, Returns a Rotation from two floating point values
angleevelation)
defining the angle around the target (degrees) and the
elevation above the target (degrees). Used with
VectorMath.orbitPos to set the position. If anglearound
is zero, you're looking along the Z axis.
headingDegrees(rotation)
Returns an angle in degrees that is the direction in
which an object with the given rotation is facing (0
degrees is along Z axis)
lookAtRot(vectorFrom,
vectorAt)
Returns a Rotation given a Vector you're looking from
and a Vector you're looking at.
inverseRot(rotation)
Returns a new Rotation that is the inverse of the given
Rotation.
Examples
var rot1=new Rotation(0,10,0);
var rot2=new Rotation(45,0,0);
var result=RotationMath.add(rot1,rot2);
See Also
Script Reference
4.3.7.34 UtilMath
A collection of useful general purpose mathematical functions.
DX Studio™ Editor
146
Properties & Methods
pi
Returns PI as a float.
degToRad(angle)
Returns an angle converted from degrees to radians.
radToDeg(angle)
Returns an angle converted from radians to degrees.
randomIntRange
(from,to)
Returns an integer in the range from low to high inclusive.
randomSeed(seed)
Initialize the UtilMath random number generator with an integer
seed (if you don't supply a parameter, it will initialize with the
pc's timer).
angleChangeDegrees Returns a float for the difference in degrees between two
(from, to)
headings/angles. This allows for the wrap around at 360.0, so
the change between 350.0 and 10.0 is 20.0.
Examples
var myval=UtilMath.degToRad(90.0); // 90 degress returned in radians
See Also
Script Reference
4.3.7.35 VectorMath
A collection of useful mathematical functions for manipulation of vectors.
Methods
length(vector)
Returns the magnitude of a single vector (float).
distance(vector,vector)
Returns the distance between two points (float).
dot(vector,vector)
Returns the dot product of two vectors (float).
cross(vector,vector)
Returns the cross product of two vectors (vector).
normalize(vector)
Returns a normalized vector with the same direction as
the given vector and a length of 1.
add(vector,vector)
Returns a vector that is the sum of the two given
vectors.
subtract(vector,vector)
Returns a vector that is the first vector minus the
second vector.
scale(vector,scale)
Returns a vector scaled by the floating point value
'scale'.
rotate(vector, rotation)
Rotates the given Vector by the Rotation.
orbitPosHeading(point,
anglearound, angleevelation,
distance)
Returns a Vector position around a Vector defining a
central point, then three floating point values defining
the angle around the point (degrees), the elevation
above the point (degrees) and the distance from the
point. Used with RotationMath.orbitRot to set the
rotation. If anglearound is zero you're looking along the
Z axis. Note: This replaces orbitPos.
147
DX Studio™ Help
Examples
var myvector=new Vector(120,150,45);
var mag=VectorMath.length(myvector);
print("Magnitude of vector is "+mag);
See Also
Script Reference
4.3.8
Other Functions
Here are some other useful functions that can be used without a collection.
Methods
alert("<message>")
Pops up a dialog box displaying the <message>.
print("<message>")
Sends the <message> to the console, displayed
over the DX Studio document.
Examples
function onClick()
{
print("The button has been clicked!");
console.
}
// When clicked, send this message to the
See Also
Script Reference
4.3.9
XML Reference
Editing XML documents directly is not usually necessary, and should
only be attempted by advanced users.
All descriptive data in DX Studio™ is stored in standard XML format. In DX Studio™,
you can edit this data directly, and see the results reflected in your document as soon
as you save your changes.
XML is widely documented. A good introduction to the specification can be found here:http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnxml/html/
understxml.asp
Example - Simple XML File from DX Studio
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<dxstudio version="1.0" width="800" height="600">
<scene id="scene1" src="scene_1.dxsscene"/>
<layer id="background" sceneid="scene1"/>
</dxstudio>
DX Studio™ Editor
148
See Also
Script Reference
Introduction
5
DX Studio™ Player
5.1
Overview
The DX Studio™ Player is a used to view your documents. The player is coded in fast,
low level C++ and thus does not require the .Net Framework in order to run.
If the player is launched without a filename, a file selection dialog will appear. You can
then choose which '.dxstudio' document that you want to play.
To exit the player at any time, you can press ALT-X.
Standard Player Controls
SHIFT+F11 - takes a screenshot of the player window
CTRL+SHIFT+F11 - takes a screenshot of the entire screen
CTRL+F12 - displays current frame rate
ARROW KEYS - move through the scene (moves only the camera on the current layer
in a multi-layered document)
PAUSE - pauses/resumes the main document timer
ALT+X or ESCAPE - exits the player application
For security in a kiosk enviornment, you can enable Kiosk Mode to prevent authorized
access to Windows.
5.2
Debugger
If you right click in the player window and choose the 'Debug' option, the following
window will appear:-
149
DX Studio™ Help
This shows the different scripts that are running, and displays the current values of top
level variables.
You can also get/set variables and execute functions using the 'Execute Script Now' text
box.
Examples
Type print("hello"); into the box and click Execute. This will cause the console to
display 'hello'.
Type scenes.scene_1.script.myvar=2; into the box and click Execute. This will set
the current value of 'myval' in 'scene_1' to 2.
Type scenes.scene_1.script.myvar into the box and click Execute. This will show the
current value of 'myval' in 'scene_1' in the 'Result' box.
5.3
Redistributing DX Studio™
You can freely redistribute any files created with a registered version of DX Studio™.
The freeware edition is for non-commercial use only, and files produced with it should
DX Studio™ Player
150
not be distributed for profit.
For ActiveX control distribution, you can redistribute a free player either by downloading
the installer, or using the following link directly...
http://www.dxstudio.com/downloads/DXWebSetupPlayer.exe
For Windows XP systems, the player download is 3Mb. For pre-XP systems a Windows
Installer bootstrapper is included, which makes the download 6Mb. The correct version
is downloaded automatically.
If you are embedding the control in a web page, you can use the 'CODEBASE'
parameter as described in the ActiveX section to perform an automatic download of the
control.
DXStudioPlayerSetup.exe
· This setup will install the ActiveX player control and register DX Studio™ document
types with the shell.
· The component itself will perform a DirectX 9 upgrade if you haven't already installed
it.
· If you are redistributing an EXE built with DX Studio, you do NOT need to install the
player separately first, as it is built in to the EXE.
Introduction
5.4
Kiosk Mode
A powerful feature of the DX Studio Player is the ability to lock down Windows and stop
a user performing any other functions other than those available in the DX Studio
document. For example, if you have a display kiosk running an interactive tour, you
don't want people to be able to ALT-TAB or CTRL-ALT-DEL out of the application and
access the Windows desktop.
To lock down a PC into kiosk mode, you must first compile your DX Studio document as
an EXE. Normally this document should also be set to 'change screen resolution to fit
document' in the Director Properties dialog.
Save the EXE to the main hard drive, eg. C:\kiosk\myapp.exe
Open a Command Prompt window (Start -> Programs -> Accessories -> Command
Prompt), and navigate to the directory the EXE was saved to.
e.g.
cd \kiosk
You can now choose between two different boot modes...
· Auto-launch only
The EXE will run automatically on boot, but the current user must provide login details
151
DX Studio™ Help
every time. CTRL+ALT+DEL is still available.
To enable this mode, type the name of the EXE followed by the flag /KioskBoot (please
note this is case sensitive)
e.g.
myapp /KioskBoot
· Complete kiosk mode
On power-up, the system will automatically log in with the username/password
provided and launch straight into the kiosk EXE. All system commands such as ALT
+TAB and CTRL+ALT+DEL are disabled.
Ideally, you should configure a dedicated user account, for example 'KioskUser'. You
should be logged in as this user when you configure the /KioskBoot mode.
To enable this mode, type the name of the EXE followed by the flag /KioskBoot (case
sensitive), followed by the username and password to be used to log in (again case
sensitive).
e.g
myapp /KioskBoot Administrator adminrules0k
or
myapp /KioskBoot KioskUser password
Removing kiosk mode
To undo the changes made my /KioskBoot, you should open a command prompt to the
directory of the EXE and launch it with the flag /NoKioskBoot.
e.g.
myapp /NoKioskBoot
This restores the PC to normal operation with no auto-logins and no application launch.
To get to a command prompt in complete kiosk mode, hold down SHIFT as Windows
boots and you will be able to login as a different account. Run the app from a command
prompt with the /NoKioskBoot flag and restart. Log in to the original account, and CTRL
+ALT+DEL will now be active again. You should now be able to terminate the player.
Launch the EXE again with the /NoKioskBoot flag from this account to completely
remove the kiosk mode.
6
DX Studio™ ActiveX
6.1
Overview
DX Studio™ presentations can be embedded in web pages, Microsoft® Office®
applications such as PowerPoint® or Excel®, or any other ActiveX compliant
152
applications.
You can even create your own Visual Studio applications that can communicate with DX
Studio™ documents embedded inside them.
Please see the following sections for more information...
Embedding
Embedding
Embedding
Embedding
in
in
in
in
FrontPage
Internet Explorer
PowerPoint
Visual Studio
For a full list of the ActiveX methods, properties and events, please see the COM
reference guide...
COM Interface Reference
6.2
Embedding in FrontPage
· Open FrontPage and go to the page where you want to add the player in 'Design'
view.
· From the 'Insert' menu choose 'Web Component...'.
· From the 'Insert Web Component' dialog, choose 'Advanced Controls' as the
component type, and 'ActiveX Control' as the sub type.
· Press 'Next' to continue.
· From the next list, choose 'DX Studio Player' as the control to add and press 'Finish'.
153
DX Studio™ Help
Tip: If 'DX Studio Player' is not in the list, press the 'Customize...' button and check
the box next to 'DX Studio Player' in the dialog's list box, then press OK and you
should be able to select it.
· Right click on the control and go to 'ActiveX Control Properties...'.
· Go to the 'Parameters' tab on the dialog, and double click the 'src' parameter to edit
it.
· Set the value to type 'Data', and enter the full URL of the '.dxstudio' file you want to
play.
That's it - preview the result by pressing the 'Preview' button at the bottom of the page.
6.3
154
Embedding in Internet Explorer
·
·
·
·
Create or open your DX Studio document in the editor.
At the director level, choose 'Build HTML' from the tools menu.
Select a location for the HTML file that will be created and press OK.
The document should now pop up inside Internet Explorer.
Generated inside the HTML code is also a automatic download object. That is, if
someone tries to view the page without having the DX Studio Player installed, it will
trigger the download automatically. You can safely remove this object if you don't want
this behaviour.
Note 1: Before posting to a website, you should change the 'src' property to be the
URL of the DX Studio document instead of the absolute disk file location, which would of
course not be available to a web user.
Note 2: If your web server refuses to allow downloads of documents that aren't of
a recognised type, you can safely rename your DX Studio document to use the .ZIP file
extension. You should remember to also change the 'src' property in the HTML to
reflect this name change.
6.4
Embedding in PowerPoint
· Ensure DX Studio™ Player is installed on the machine that you are running
PowerPoint on.
· Launch PowerPoint.
· From the 'Insert' menu choose 'Object...' to bring up a list of ActiveX objects.
· Select 'DX Studio Player' from the list box and press OK.
155
DX Studio™ Help
· Right click on the new object and go to 'Properties'.
· From the 'Properties' window, set the 'src' parameter to the full URL or full filename of
the '.dxstudio' file you want to play.
· For example, if the file 'chart1.dxstudio' is located in 'c:\presentation', you should
set 'src' to be 'c:\presentation\chart1.dxstudio'.
That's it - click 'View Show' in the 'Slide Show' menu to see the object running in the
presentation.
6.5
Embedding in Visual Studio
If you don't have the DX Studio tab in your toolbox, try running the
DXStudioVisualStudio.exe application. This will configure Visual Studio with the DX
Studio control automatically. It is located the bin subfolder of your DX Studio install
folder. e.g. c:\program files\worldweaver\dx studio\bin\DXStudioVisualStudio.exe
How to manually add DX Studio to your toolbox
·
·
·
·
Create or open a Visual Studio .Net project.
In the 'Toolbox' window, go to the 'Components' tab.
Right click in the Components area and choose 'Add/Remove Items...'.
In the Customize Toolbox dialog, click the 'COM Components' tab.
· Check the box for 'DX Studio Player' and press OK.
156
Using the DX Studio Player component
· Go to a new or existing 'Form' in 'Design View' mode, or for C++ projects, open the
dialog resource.
· Click on the 'DX Studio Player' button in the toolbox, then click on the form to place
the object. In the 'Properties' window for the new object, set the 'src' parameter to
the full URL or full filename of the '.dxstudio' file you want to play. For example, if
the file 'chart1.dxstudio' is located in 'c:\presentation', you should set 'src' to be 'c:
\presentation\chart1.dxstudio'.
· That's it - build and run the project and the form will display the document exactly as
defined in the designer.
Hooking up events in Visual Studio
A powerful feature of the COM control is the ability to send and receive script
commands between the document and the container application.
Your application can use the 'Send' command to send script to the control, and
override the 'Receive' event to handle commands sent from the document.
A script command sent to a document can only call a director level function.
For example, in C# the Send function passes the following command...
mydocontrol.Send("system.script.myFunction();");
...which is valid if defined in the director script is...
function myFunction()
{
// do something
}
To receive commands from the document, you override the 'Receive' event and process
the command string yourself. The command string can be sent from anywhere in the
document using the following syntax...
function onClick()
{
shell.send("userclickedmybutton");
}
Note: The receive event is sent from a separate thread used by the engine, and so
will not be in the same thread as your application. If this causes a problem, you should
use the receive function to post a message to your main thread, telling it to perform
any synchronous activity.
For full control of your DX Studio Document, please see the COM Interface
documentation.
157
6.6
DX Studio™ Help
COM Interface
The DX Studio Player has a full featured COM interface for use in your own applications.
The simplest way to access the object is to add the ActiveX component into your Visual
Studio form as described here.
Then, from C# or VB.Net, you should use the namespace 'DXStudioPlayer', for
example...
using DXStudioPlayer;
You can then call the DXStudioPlayer methods to access and control your document.
6.6.1
DXStudioPlayer
You can control the DX Studio Player though this class.
For example...
...
Scene scene1;
SoundEffect soundfire;
WorldObject ship;
axDXStudioPlayer1.GetScene("scene_1", out scene1);
scene1.GetWorldObject("ship",out ship);
scene1.GetSoundEffect("fire",out soundfire);
ship.SetPosition(0.0f,0.0f,0.0f);
soundfire.Play();
...
Note:
You should only attempt to access and control objects after the Load event has been
fired, telling you that the DX Studio document has finished loading.
6.6.1.1
Methods
6.6.1.1.1 GetScene
Fetches a reference to a 'Scene' object of the given name in the current DX Studio
document.
Definition
public bool GetScene(string scenename, out Scene obj);
Parameters
scenename
System.String. [in] name of the scene to find
obj
Scene. [out] the Scene found
Return Value
158
System.Boolean - true if the function is successful.
6.6.1.1.2 IsKeyDown
Tests the state of the named keyboard key. A full list of valid key names can be found
here.
Definition
public bool IsKeyDown(string keyname);
Parameters
keyname
System.String. [in] name of the key to test.
Return Value
System.Boolean - true if the key is down, false if the key is up.
6.6.1.1.3 DirectorScriptExecuteFunction
Deprecated - please use Send() instead using the system.script prefix.
e.g. axDXStudioPlayer1.Send("system.script.myfunc()");
6.6.1.1.4 DirectorScriptGetVariable
Gets a script variable for the document at director level.
Definition
public bool DirectorScriptGetVariable(string variablename, out string value);
Parameters
variablename System.String. [in] name of the variable to set
value
System.String. [out] the current value of the variable
Return Value
6.6.1.1.5 DirectorScriptSetVariable
Sets a script variable attached to the document at director level.
Definition
159
DX Studio™ Help
public bool DirectorScriptSetVariable(string variablename, string value);
Parameters
value
System.String. [in] the new value of the variable
Return Value
6.6.1.1.6 Send
Passes a single line of script into the engine for immediate execution.
Definition
public bool Send(string script);
Parameters
script
System.String. [in] script to execute
Return Value
6.6.1.1.7 NetworkSend
Sends a line of script to all players with the same network group identifier. For more
advanced sending, you should get a NetworkSet representing the target group/
document/instance using the NetworkGetNetworkSet function.
Definition
public bool NetworkSend(string script);
Parameters
script
System.String. [in] script to execute
Return Value
6.6.1.1.8 NetworkOnlyBegin
Called to begin a network only session.
If you don't want to create a DX Studio Player window but do want access to the
network communications layer, this function should be used.
Definition
public bool NetworkOnlyBegin();
Parameters
None.
Return Value
6.6.1.1.9 NetworkOnlyEnd
Called to terminate a network only session.
If you don't want to create a DX Studio Player window but do want access to the
network communications layer, this function should be used.
Definition
public bool NetworkOnlyBegin();
Parameters
None.
Return Value
6.6.1.1.10 SendAndWaitForCapture
Sends a script command and waits for an image file to be returned.
Definition
public bool NetworkGetScreenCapture(string remoteidentifier, out object imagedata);
Parameters
160
161
DX Studio™ Help
remoteidentifier
System.String. [in] a guid string identifying the document/
instance that will send the screen capture.
imagedata
object. [out] a binary object containing a complete image file in
memory
Return Value
6.6.1.1.11 UseExistingWindow
Tells the DX Studio Player to use a specific window handle.
6.6.1.1.12 UseExistingDevice
Tells the DX Studio Player to use a Direct3D device that has already been created.
6.6.1.1.13 GetDevicePointer
Returns the actual main DirectX COM object 'Device' pointer so you can call all DirectX
related functions.
Before calling any DirectX functions, you should call RenderLock to prevent other
threads accessing the display.
e.g.
uint pdev;
if (!axDXStudioPlayer1.GetDevicePointer(out pdev))
return;
Device dev = new Device((IntPtr)pdev);
6.6.1.1.14 RenderLock
Prevents any other threads from writing to the DirectX render target. Useful if you
want to perform a screen capture, but don't want the surface being updated part of the
way through.
Call RenderUnlock when finished.
6.6.1.1.15 RenderUnlock
Allows other threads to access the DirectX render target.
6.6.1.1.16 GetPlayerTime
Returns a floating point value representing the current system.timer value in the
player.
6.6.1.2
162
Properties
6.6.1.2.1 src
The full filename or URL of the DX Studio document (.dxstudio) to load.
Definition
public string src { get; set; }
Property Value
System.String
This property is read/write.
6.6.1.2.2 Version
The version string identifiers the version of the DX Studio Player that is being used.
Definition
public string Version { get; }
Property Value
System.String
This property is read only.
6.6.1.2.3 NetworkInstanceId
Returns the network instance identifier (a GUID as a string). This is automatically set
when the player first runs.
An instance identifier can be useful to distinguish between different users running the
same document, for example for identifying individual players in a game.
Definition
public string NetworkInstanceId { get; }
Property Value
System.String
163
DX Studio™ Help
6.6.1.2.4 NetworkDocumentId
Returns the network document identifier (a GUID as a string). This should be set in the
document's director level properties.
A document identifier can be useful to distinguish between a control panel or display in
a network group.
Definition
public string NetworkDocumentId { get; set; }
Property Value
System.String
6.6.1.2.5 NetworkGroupId
Returns the network group identifier (a GUID as a string). This should be set in the
document's director level properties.
The network group is a logical collection of documents that want to communicate with
each other. You need to know the group identifier to communicate with other DX
Studio documents on a server, so the group identifier should be copied and pasted
between all documents that need to communicate with each other.
Definition
public string NetworkGroupId { get; set; }
Property Value
System.String
6.6.1.2.6 ManualCreateAndUpdate
If you set this property to true, you must create your own Direct3D device and window,
and also handle your own update/render loop.
Definition
164
public string ManualCreateAndUpdate { get; set; }
Property Value
System.String
6.6.1.2.7 CacheDirectory
Returns the file system directory where resources for the director level are cached.
Definition
public string CacheDirectory { get; }
Property Value
System.String
6.6.1.2.8 Password
If you have password protected a document you can submit the unlock password at
runtime by setting this string property.
6.6.1.2.9 CustomStreamBackgroundCol
Set to a string RGB color value. This will determine the background colour to be
displayed while a DX Studio document is being streamed from a URL.
e.g.
<PARAM name="CustomStreamBackgroundCol" value="#ff0000">
6.6.1.2.10 CustomStreamLogoURL
Set to a string URL locating an image file. This will determine the logo to be displayed
while a DX Studio document is being streamed from a URL. A full (not a relative) URL
must be used.
e.g.
<PARAM name="CustomStreamLogoURL" value="http://www.dxstudio.com/images/
boxproduct.jpg">
165
DX Studio™ Help
6.6.1.2.11 HideInactiveInfo
If set to true the player won't draw the blue screen and show the document source in
design mode.
6.6.1.3
Events
6.6.1.3.1 FrameUpdate
This event is fired once for every frame being displayed. A FLOAT is also passed which
represents the amount of time that has passed since the last frame was displayed.
Definition
C#
public event EventHandler FrameUpdate;
JavaScript
<script for="dxstudioplayer" event="FrameUpdate(seconds)">
...
</script>
6.6.1.3.2 Load
This event is fired when the DX Studio document has finished loading as is about to be
displayed.
Definition
C#
public event EventHandler Load;
JavaScript
<script for="dxstudioplayer" event="Load(result)">
alert('Loaded: ' + result);
</script>
6.6.1.3.3 Receive
This event is fired in response to a 'shell.send' script command in the DX Studio
document.
Definition
C#
public event EventHandler Receive;
JavaScript
<script for="dxstudioplayer" event="Receive(msg)">
alert('Receive: ' + msg);
</script>
6.6.2
Layer
The Scene class provides access to a scene in a DX Studio document.
6.6.2.1
Methods
6.6.2.1.1 MoveUp
Moves the layer up in the list of layers to be drawn (behind other layers).
Definition
public bool MoveUp();
Return Value
6.6.2.1.2 MoveDown
Moves the layer down in the list of layers to be drawn (in front of other layers).
Definition
public bool MoveDown();
Return Value
6.6.2.2
Properties
6.6.2.2.1 Visible
Gets/sets the visibility of the layer.
Definition
public bool Visible { get; set; }
Property Value
System.Boolean
166
167
DX Studio™ Help
6.6.2.2.2 Index
Gets/sets the index of the layer in the list of layers to be drawn. 0 is the layer at the
very back, 1 next, etc.
Definition
public int Index { get; set; }
Property Value
System.Int32
6.6.3
NetworkSet
6.6.3.1
Methods
6.6.3.1.1 Send
Sends a command over the network to everyone in this NetworkSet.
Definition
public bool Send(string script);
Return Value
6.6.3.1.2 GetDocumentIdArray
Returns an array of strings that contain the identifiers of all of the documents in this
NetworkSet.
In order for this function to work, the NetworkSet must represent a group identifier.
Definition
public bool GetDocumentIdArray(out object obj); // where obj can be converted to string []
Return Value
168
6.6.3.1.3 GetInstanceIdArray
Returns an array of strings that contain the identifiers of all of the player instances in
this NetworkSet.
In order for this function to work, the NetworkSet must represent a group or a
document.
Definition
public bool GetInstanceIdArray(out object obj); // where obj can be converted to string []
Return Value
6.6.3.2
Properties
6.6.3.2.1 Id
Gets the identifier of this NetworkSet (a GUID as a string).
This identifier may refer to a group, document or instance.
Definition
public bool Id { get; }
Property Value
System.Boolean
6.6.4
Scene
6.6.4.1
Methods
6.6.4.1.1 AddWorldObject
Returns a new 'WorldObject' with the given new id and type. The type should be either
the mesh/bitmap definition id, or a built in type such as 'camera' or 'light'.
Definition
public bool AddWorldObject(string objectname, string objecttype, out WorldObject obj);
Parameters
169
DX Studio™ Help
objectname
System.String [in] name of the world object to create
objecttype
System.String [in] type of the object to create
obj
WorldObject [out] the WorldObject pointing to the newly created object
Return Value
6.6.4.1.2 GetSoundEffect
Returns a 'SoundEffect' that references the sound in the scene of the given name.
Definition
public bool GetSoundEffect(string soundname, out SoundEffect obj);
Parameters
soundname
System.String. [in] name of the sound to find
obj
SoundEffect. [out] the SoundEffect found
Return Value
6.6.4.1.3 GetWorldObject
Returns a 'WorldObject' that references the object in the world that matches the given
name.
Definition
public bool GetWorldObject(string objectname, out WorldObject obj);
Parameters
objectname
System.String. [in] name of the world object to find
obj
WorldObject. [out] the WorldObject found
Return Value
170
6.6.4.1.4 GetWorldObjectIdArray
Returns an array of strings representing all of the names of the objects currently in the
world for this scene.
Definition
public bool GetWorldObjectIdArray(out object obj);
Depending on the language you're using, you will need to cast the general 'obj' object
to a string array before use.
e.g.
object obj;
scene.GetWorldObjectIdArray(out obj);
string [] ids = (string []) obj;
You can then use GetWorldObject on each id to find out more about the objects.
e.g.
foreach(string id in ids)
{
WorldObject wo;
if (scene.GetWorldObject(id, out wo))
{
// check further/do something with the WorldObject
}
}
Parameters
obj
System.Array [out] array of strings (BSTRs) representing the id of each
object in the world
Return Value
6.6.4.1.5 GetObjectDef
Finds an object definition in a scene by name (either a mesh or a bitmap), and returns
an ObjectDef.
Definition
public bool GetObjectDef(string objectdefname, out ObjectDef obj);
Parameters
objectdefname System.String. [in] name of the object definition to find
obj
Return Value
ObjectDef. [out] the ObjectDef found
171
DX Studio™ Help
6.6.4.1.6 RemoveWorldObject
Removes an object from the world with the given identifier.
Definition
public bool RemoveWorldObject(string objectname);
Parameters
objectname
System.String [in] name of the world object to remove
Return Value
6.6.4.1.7 ScriptExecuteFunction
Executes a function that has been defined in script for the scene.
Definition
public bool ScriptExecuteFunction(string functionname);
Parameters
functionname System.String. [in] name of the function to call
Return Value
6.6.4.1.8 ScriptGetVariable
Gets a script variable for the scene.
Definition
public bool ScriptGetVariable(string variablename, out string value);
Parameters
value
172
Return Value
6.6.4.1.9 ScriptSetVariable
Sets a script variable attached to the scene.
Definition
public bool ScriptSetVariable(string variablename, string value);
Parameters
value
Return Value
6.6.4.1.10 SetMediaVolume
Sets the current volume of the media in the player.
Definition
public bool SetMediaVolume(float volume);
Parameters
volume
System.Float. [in] value between 0 and 1, where 0 is silent and 1 is full
volume.
Return Value
6.6.4.2
Properties
6.6.4.2.1 CacheDirectory
Returns the file system directory where resources for this scene are cached.
Definition
public string CacheDirectory { get; }
173
DX Studio™ Help
Property Value
System.String
6.6.5
WorldObject
The WorldObject class provides access to individual objects in the DX Studio scene.
6.6.5.1
Methods
6.6.5.1.1 SetPosition
Sets the position of a 2D or 3D object.
Definition
public bool SetPosition(float x, float y, float z);
Parameters
x
System.Float. [in] new x position of the object in pixels if 2D or in world
coordinates if 3D.
y
System.Float. [in] new y position of the object in pixels if 2D or in world
coordinates if 3D.
z
System.Float. [in] new z position of the object in world coordates.
Ignored if 2D.
Return Value
6.6.5.1.2 SetScale
Sets the scale of a 2D or 3D object.
Definition
public bool SetScale(float x, float y, float z);
Parameters
x
System.Float. [in] new x scale of the object in pixels if 2D or in world
coordinates if 3D.
174
y
System.Float. [in] new y scale of the object in pixels if 2D or in world
coordinates if 3D.
z
System.Float. [in] new z scale of the object in world coordates.
Ignored if 2D.
Return Value
6.6.5.1.3 SetRotation
Sets the rotation of 3D object. Rotation is described as a unit quaternion with x,y,z,w
properties.
Definition
public bool SetRotation(float x, float y, float z, float w);
Parameters
x
System.Float. [in] new x component as part of a quaternion.
y
System.Float. [in] new y component as part of a quaternion.
z
System.Float. [in] new z component as part of a quaternion.
w
System.Float. [in] new w component as part of a quaternion.
Return Value
6.6.5.1.4 SetColor
Sets the color of an object.
Definition
public bool SetColor(float r, float g, float b);
Parameters
r
System.Float. [in] new red channel value between 0 and 1.
g
System.Float. [in] new green channel value between 0 and 1.
b
System.Float. [in] new blue channel value between 0 and 1.
Return Value
175
DX Studio™ Help
6.6.5.1.5 GetPosition
Gets the position of a 2D or 3D object.
Definition
public bool GetPosition(out float x, out float y, out float z);
Parameters
x
System.Float. [out] current x position of the object in pixels if 2D or in
world coordinates if 3D.
y
System.Float. [out] current y position of the object in pixels if 2D or in
z
System.Float. [out] current z position of the object in world coordates.
Ignored if 2D.
Return Value
6.6.5.1.6 GetScale
Gets the scale of a 2D or 3D object.
Definition
public bool GetScale(out float x, out float y, out float z);
Parameters
x
System.Float. [out] current x scale of the object in pixels if 2D or in
y
System.Float. [out] current y scale of the object in pixels if 2D or in
z
System.Float. [out] current z scale of the object in world coordates.
Ignored if 2D.
Return Value
6.6.5.1.7 GetRotation
Sets the rotation of 3D object. Rotation is described as a unit quaternion with x,y,z,w
properties.
Definition
public bool GetRotation(out float x, out float y, out float z, out float w);
Parameters
x
System.Float. [out] current x component as part of a quaternion.
y
System.Float. [out] current y component as part of a quaternion.
z
System.Float. [out] current z component as part of a quaternion.
w
System.Float. [out] current w component as part of a quaternion.
Return Value
6.6.5.1.8 GetColor
Gets the color an object.
Definition
public bool GetColor(out float r, out float g, out float b);
Parameters
r
System.Float. [out] current red channel value between 0 and 1.
g
System.Float. [out] current green channel value between 0 and 1.
b
System.Float. [out] current blue channel value between 0 and 1.
Return Value
6.6.5.1.9 PerformClick
Simulates a click on the object.
Definition
public bool PerformClick();
Parameters
None.
Return Value
176
177
DX Studio™ Help
6.6.5.1.10 ScriptExecuteFunction
Deprecated - please use Send() instead using the scenes.xxx.script prefix.
e.g. axDXStudioPlayer1.Send("scenes.myscene.script.myfunc()");
6.6.5.1.11 ScriptGetVariable
Gets a script variable that has been attached to an object.
Definition
public bool ScriptGetVariable(string variablename, out string value);
Parameters
value
Return Value
6.6.5.1.12 ScriptSetVariable
Sets a script variable attached to an object.
Definition
public bool ScriptSetVariable(string variablename, string value);
Parameters
value
Return Value
6.6.5.1.13 SetSequence
Sets the keyframe sequence of this object. Note that this is different to an animation.
Definition
public bool SetSequence(string sequencename);
178
Parameters
sequencenam System.String. [in] name of the sequence
e
Return Value
6.6.5.1.14 SetAnimation
Sets the internal mesh animation of this object. Note that this is different to a
sequence.
Definition
public bool SetAnimation(string animationname);
Parameters
animationnam System.String. [in] name of the animation
e
Return Value
6.6.5.1.15 SetText
Sets the text string associated with this object. For a dynamic text object, this will
change the string displayed.
Definition
public bool SetText(string newtext);
Parameters
newtext
System.String. [in] new text string
Return Value
179
6.6.5.2
DX Studio™ Help
Properties
6.6.5.2.1 Id
Gets the identifier (name) of the world object.
Definition
public string Id { get; set; }
Property Value
System.String
6.6.5.2.2 Text
Gets/sets the text associated with the world object. For a dynamic text object, this
represents the text string that will be displayed.
Definition
public string Text { get; set; }
Property Value
System.String
6.6.5.2.3 Opacity
Gets/sets the floating point opacity for the world object. The value is measured
between 0 and 1 where 0 is invisible and 1 is solid.
Definition
public string Opacity { get; set; }
Property Value
System.Float
180
6.6.5.2.4 Timer
Gets/sets the floating point timer for the world object. The value is measured in
seconds.
Definition
public string Timer { get; set; }
Property Value
System.Float
6.6.5.2.5 Type
Gets/sets the type of the world object. This may be a built in type such as 'camera' or
'effectpoint', or the name of a mesh or bitmap definition.
Definition
public string Type { get; set; }
Property Value
System.String
6.6.5.2.6 Visible
Gets/sets the run-time visibility of the world object. If FALSE, the object is hidden from
being drawn or selected.
Definition
public string Visible { get; set; }
Property Value
System.Boolean
181
6.6.6
DX Studio™ Help
SoundEffect
The SoundEffect class provides access to all of the sounds stored in a scene.
6.6.6.1
Methods
6.6.6.1.1 Play
Plays the sound once through.
Definition
public bool Play();
Parameters
None.
Return Value
6.6.6.1.2 PlayLooped
Plays the sound in a continuous loop until explicitly stopped.
Definition
public bool PlayLooped();
Parameters
None.
Return Value
6.6.6.1.3 Stop
Stops the sound from playing immediately.
Definition
public bool Stop();
Parameters
None.
Return Value
182
6.6.6.1.4 SetVolume
Sets the current volume of the sound.
Definition
public bool SetVolume(float volume);
Parameters
volume
System.Float. [in] value between 0 and 1, where 0 is silent and 1 is full
volume.
Return Value
6.6.6.1.5 Set3DPositionAndVelocity
Sets the position and velocity of the sound for the 3D spatial effect. If the sound is not
moving, just enter zero for the posxv, posyv and poszv values.
Note - for this to work, you must set the sound to be of type 'positioned' in the Sounds
window of the scene in DX Studio.
Definition
public bool Set3DPositionAndVelocity(float posx, float posy, float posz, float posxv, float
posyz, float poszv);
Parameters
posx
System.Float. [in] new x position of the sound.
posy
System.Float. [in] new y position of the sound.
posz
System.Float. [in] new z position of the sound.
posxv
System.Float. [in] new x velocity of the sound.
posyv
System.Float. [in] new y velocity of the sound.
poszv
System.Float. [in] new z velocity of the sound.
Return Value
6.6.6.2
Properties
None.
183
DX Studio™ Help
7
Other Applications
7.1
DX Studio Server
For networked documents to communicate you need to install the DX Studio Server.
There are two different ways of running the server...
1. By just copying DXStudioServer.exe from the bin directory of your DX Studio
install folder onto a server computer and running it.
2. By copying the DXStudioServiceSetup.msi from the bin directory of your DX
Studio install folder to your server and running it. This will install the server as a
Windows Service. This is the recommended method and it is well suited to web
servers. The service makes sure the server is started when the computer reboots, and
will restart the server should it stop running.
By default, the server will run on port 9620. You can change this port to any you wish
by the following different methods...
1. If you're running the server directly as an EXE, just add -port and then the
portnumber as an option when launching from a console...
e.g.
DXStudioServer -port 1234
2. If you're running the server using the service, you need to find and edit the INI file
from the install directory, which by default is c:\Program Files\Worldweaver\DX Studio
Service\
Use notepad to edit the file DXStudioService.ini.
At the end of the property for CommandLine, add the -port option...
CommandLine = dxstudioserver.exe -port 1234
Save the file and restart the service to make the change.
7.2
DX Studio in Visual Studio
This simple application will add/remove the DX Studio tools from your Visual Studio
toolbox.
The program is located in your install folder in the bin subdirectory, e.g. c:\program
files\worldweaver\dx studio\bin\DXStudioVisualStudio.exe, or it can be launched from
DX Studio in the Help -> Visual Studio menu.
Other Applications
184
To add the DX Studio tab to the toolbox, click the 'Add To Toolbox' button. Similarly
you can remove the tab by clicking the 'Remove From Toolbox' button.
Click 'Finished' when you have finished adding/removing. You will need to restart
Visual Studio to see any changes.
7.3
FishCube
This application can be used to convert fish-eye photographs into a cube map in an
environment file. An environment file (.dxenv) can then be used as a background in a
DX Studio scene to give a 'long distance' view. This is ideal for displaying distant
mountains or a cloudy sky.
Firstly you need two fish-eye photographs, similar to those shown here. If you don't
have any to hand, you can use the sample photos found in the 'library' folder of your
DX Studio installation path. (e.g. c:\program files\worldweaver\dx studio\library) The
files are called fisheye_manorfront.jpg and fisheye_manorback.jpg.
They represent the front 180 degree hemisphere and rear 180 degree hemisphere that
can be captured with a fish eye lens to give full 360 degree coverage.
Select these images in the 'front fisheye image' and 'rear fisheye image' boxes in the
FishCube application.
You also need to decide on the resolution of the final cubemap - a larger resolution uses
185
DX Studio™ Help
more memory but provides better quality. This is set in the 'Strip Height' field in the
FishCube application. A good all-round value is 512 pixels.
Now you can test the result by clicking the 'Build Environment...' button. You can then
save the .dxenv file to the hard drive.
In a 3D scene in DX Studio, open the 'Environments' window and click 'Add
Environment...'. Browse to the file you just saved, and click OK. Answer 'yes' to
whether you want to set the background to the new environment. The 'camera'
viewport will now show the results - click and drag the right mouse button in this
viewport to examine your cubemap.
If the edges of the two images do not align, use the 'Options' section of the FishCube
application to fine tune the blend between the front and back hemispheres.
See Also
Building Environments with Terragen
8
Appendix
8.1
Freeware Limitations
If you're using the freeware version of DX Studio, the following restrictions will apply...
· No more than 10 mesh/bitmap definitions per scene
· Resource export/write to library disabled
· Network communications are disabled
You can purchase a full edition of DX Studio from the product website at http://www.
dxstudio.com/buy.aspx
8.2
KeyNames
This is a full list of the named keyboard keys available...
escape, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, minus, equals, backspace, tab, q, w, e, r, t, y, u, i,
o, p, leftbracket, rightbracket, enter, leftcontrol, a, s, d, f, g, h, j, k, l, semicolon,
apostrophe, grave, lshift, backslash, z, x, c, v, b, n, m, comma, period, slash, rightshift,
multiply, leftalt, space, caps, f1, f2, f3, f4, f5, f6, f7, f8, f9, f10, numlock, scroll,
numpad7, numpad8, numpad9, numpadminus, numpad4, numpad5, numpad6, numpadplus, numpad1,
numpad2, numpad3, numpad0, numpadperiod, backslash2, f11, f12, f13, f14, f15, numpadequals,
trackprev, at, colon, underline, stop, tracknext, numpadenter, rightcontrol, mute, calculator,
playpause, mediastop, volumedown, volumeup, webhome, numpadcomma, numpaddivide, sysreq,
rightalt, pause, home, up, pageup, left, right, end, down, pagedown, insert, delete,
leftwindows, rightwindows, appmenu, power, sleep, wake, websearch, webfavorites, webrefresh,
webstop, webforward, webback, mycomputer, mail, mediaselect
8.3
DX Studio File Format
The '.dxstudio' format is open for other developers to use and access.
It is 100% ZIP compatible, so to examine the contents of a dx studio document you
Appendix
186
could just add .ZIP to the end of the filename and open in a ZIP viewer.
The document demands the presence of only one file in each zip, an XML file describing
the document named 'header.xml'. It is this header file that references any other files
stored in the ZIP, although you may store extra files in the ZIP not referenced in the
header if you wish.
A document will contain scene files (.dxscene), which follow exactly the same structure.
If you rename a .dxscene file to have a .ZIP extension, you will be able to open and
examine the contents in exactly the same way as a .dxstudio document.
The scene file will also contain resources, such as mesh files, textures, sounds which
are referenced from the 'header.xml' file.
Note: The header.xml files are the same as the source shown in the editor if you
choose 'Edit XML Source...' in the director level or in a scene.
If you have a broken .dxstudio file, you can recover/edit your file with the following
process...
1. Rename the .dxstudio file to .dxstudio.zip
2. Extract the ZIP to a folder
3. Inside this new folder will be files called .dxscene - rename the offending one to .
dxscene.zip
4. Extract this scene zip to a subfolder
5. You can now edit the XML or add/remove files to match the folder in the cache
directory. Any .dx... file can be renamed as a ZIP and extracted.
6. When you're happy, re-zip the subfolder and rename the ZIP back to .dxscene.
Delete the subfolder.
7. Re-zip the main folder and rename the ZIP back to .dxstudio.
187
DX Studio™ Help
Index
-22d 35
2d scene editor
35
-3-
-E-
3d 36
3d scene editor
3d sound 101
3ds 21
36
-Aactivex 47, 151
adding 70
adding objects 93
animation 48
animations 52
avi 48, 57, 69
-Bbitmap editor
bitmaps 60
dialogs 65
director 31
Director Level Concepts 30
Director Menus 66, 83
director properties 71
director windows 67
document properties 71
documents 6
dxstudio 185
DXStudioPlayer 157
60, 103
-Ccharts 93
Color 107, 120, 143
create 37
createKeyframe 113
creating a scene 4
-Ddata
script 108
data set 78
data source 75
database 63
degrees 97
edit keyframes 81
editor 30, 60, 62
effects 56, 84, 94
Embedding in FrontPage
environments 44
events 25
exe 46
exploring 4
151
-FFace 110
File 111
FishCube 45
fonts 81
format 6, 185
formats 23
freeware 185
-Ggetting started
gif 48, 69
2, 4
-Hhere
44, 127
http://www.dxstudio.com/examples/showscreenshot.
aspx 134
Index
movies 48
mpeg 57
mpg 57
-Iimage sequence 68
import 21, 23
import and export 21
install your own server
installation 2
introduction 1
-Kkey names 185
Keyframe 113
keyframes 50, 81
keys 114, 185
-Llayer 112
layers 33
script 112
length 111
lens flare 56
Level of Detail 43, 44
lights 95
limitations 185
LOD 43, 44
look at 97
-MMaterial 120
material properties 91
materials 41
Math 121, 145, 146
max 21
media 122
menu reference
2d 83
3d 90
menus 66
mesh 123
mesh animations 52
meshes 123
modify 40
movie 69
-N28
network 28
script 124
networking 28
NetworkSet 124
-Oobject 112, 114
objects 127
script 114
onClick 108
onHoverBegin 108
onHoverEnd 108
onInit 108
onKeyChange 108
Online Library 7
onMouseDown 108
onMouseMove 108
onMouseUp 108
onMouseWheel 108
onShow 108
onUpdate 108
-PParticle 119
particles 42
player 148
portfolio 9
-RreadByteArray 111
readStringArray 111
redistributing 149
reference guide 65
resources 34
Rotation 97, 125
188
189
DX Studio™ Help
-S-
-V-
scene 126
scene properties
2d 86
3d 98
scenes 32
script 126
script 24, 25
script editor 54
script functions 27
script variables 26
scripting 53
sequences 81
setup 2
shadows 59
shapes 37, 40
shell
script 131
skin 52
skinned mesh 52
sound editor 62, 105
sounds 62
script 132
sql 63
Subgroup 133
subgroups 41
Switching 43, 44
system
script 134
Vector 144
video 57
visual studio 183
-Wwater 58
web 47
welcome 1
windows 67, 80
2d 102
3d 89
writeByteArray 111
writeStringArray 111
-Xxml reference
147
-Ttarget 97
Terragen 45
terrain 38
Texture 143
Textures 143
script 143
tutorial 9, 26, 27
Tutorials 1, 7, 30
tweening 51
-Uuser guide
30

DX Studio Help - welcome to deby.net

Transcription

Similar documents

Me on tv+instructions

The control room of Deutsche Welle

They want you to fail

Alejandro Press Kit

Launch Control XL FL Studio Guide.indd

Studio, Boezemstraat in Rotterdam (Crooswijk)

PDF - Creative Sound Studios

Try On! Studio Implementation Guide for WordPress Register to Get

December 00/January 01

footnotes