Scripting Sapphire

You can open the Sapphire 3D renderer window using the following ZeoScript command:

Sapphire.ShowWnd

You can close the Sapphire 3D renderer window using the following ZeoScript command:

Sapphire.HideWnd

You can toggle open/close the Sapphire 3D renderer window using the following ZeoScript command:

Sapphire.ToggleWnd

If the window is open, it will be closed, and if it is closed, it will be opened.

You can open the Sapphire 3D renderer window in heightfield editor mode using the following ZeoScript command:

Sapphire.EditHF

You can open the Sapphire 3D renderer window in attributes map editor mode using the following ZeoScript command:

Sapphire.EditAM

You can open the Sapphire 3D renderer window in texture map editor mode using the following ZeoScript command:

Sapphire.EditTX

To take a screen capture from Sapphire, use the following script command:

Sapphire.ScreenCap "myimagefile.bmp"

…where in the above example, “myimagefile.bmp” is the destination filename of the screen capture. If no path is given, the file will be written in L3DT's current working directory. Common image formats are supported (BMP/JPG/PNG/TGA/etc.).

To allow the user to enter the filename using a file-save dialog, use the following script command:

Sapphire.ScreenCap <z:file.SaveDlg "bmp" NULL "Bitmap image (*.bmp)|*.bmp|JPEG image (*.jpg)|*.jpg|">

To add more formats to the file selection dialog, edit the filter string above.

You can pause the the Sapphire 3D renderer window using the following ZeoScript command:

Sapphire.SetPause true

To un-pause the renderer, use the following command:

Sapphire.SetPause false

You can set the mouse mode in the Sapphire 3D renderer using the Sapphire.SetMouseMode ZeoScript command like so:

// set to the default cursor (no tool, no capture)
Sapphire.SetMouseMode 0

// set to the camera pan mode
Sapphire.SetMouseMode 1

// set to the heightfield brush tools:
Sapphire.SetMouseMode 2

// set to the attributes map brush tools:
Sapphire.SetMouseMode 3

You can set the position of the camera in Sapphire using the following ZeoScript command:

Sapphire.Camera.SetPos3d 100 200 300

… where, in the above example, 100 is the X coordinate (east/west), 200 is the Y coordinate (north/south), and 300 is the Y coordinate (up/down). Obviously, you'd want to replace the 100/200/300 numbers with the actual camera coordinates you want to use. Decimal values are allowed.

The camera coordinates are in reduced terrain vertex units, so X=100 Y=200 would put the camera on the 100th vertex in the east direction, and the the 200th vertex in the Y direction. The Z coordinate is also scaled by the horizontal scale of the heighfield, so a Z coordinate of 300 would put the camera at an altitude of 3,000m when using a 10m-resolution heightfield.

To set the elevation (up/down angle) of the camera, use the following ZeoScript command:

Sapphire.Camera.SetElev 45

…where in the above example, 45 is the camera elevation angle measured in degrees above the horizon. A value if 0 is horizontal, 90 is straight up, and -90 is straight down. Decimal values are allowed.

To set the azimuth (heading angle) of the camera, use the following ZeoScript command:

Sapphire.Camera.SetAzim 135

…where in the above example, 135 is the camera heading angle measured in degrees clockwise from north. A value if 0 is due north, 90 is east, 180 is south, and 270 is west. Decimal values are allowed.

You can open the renderer settings dialog box for Sapphire using the following ZeoScript command:

Sapphire.Settings.EditRendererCfg

You can open the hardware settings dialog box for Sapphire using the following ZeoScript command:

Sapphire.Settings.EditHardwareCfg

You can open a web-browser and automatically navigate to the Sapphire wiki page / userguide using the following ZeoScript command:

Sapphire.Help.OpenWiki

OpenGL is a state engine¹⁾, which means that it's a shockingly bad idea to try to make OpenGL do two things at once, such as call OpenGL functions from two threads. Consequently, users must be careful not to call Sapphire script commands that affect the OpenGL state from within calculation threads (e.g. inside calcman.RunCalcScript calls, or in other threaded functions).

Particular functions that must not, under any circumstances, be called from threads other than the main application thread include:

• Sapphire.ShowWnd
• Sapphire.ShowWndEx
• Sapphire.HideWnd
• Sapphire.ToggleWnd
• Sapphire.SetTexture
• Sapphire.RenderFrame
• Sapphire.EditHF
• Sapphire.EditTX
• Sapphire.ScreenCap
• Sapphire.ScreenCap2
• Sapphire.SetMouseMode

However, if you simply must call Sapphire functions from a thread, there is a work-around. The procedure is:

• call 'Sapphire.SetPause true', to pause Sapphire (this doesn't touch OpenGL, so it's safe to use in threads.)
• add your script(s) to Sapphire's script queue using Sapphire.FrameScriptQueue.AddScript, which will run your script(s) at the beginning of Sapphire's next frame when it is unpaused. Note the scripts are run in the application's main thread, not in the calling thread.
• call 'Sapphire.SetPause false' to make Sapphire resume rendering, which will then process the scripts in the queue one by one and empty it.

Plese note that 'Sapphire.SetPause true' is a blocking function, and will pause Sapphire's rendering before it returns, whereas 'Sapphire.SetPause false' is non-blocking, and may not resume frame rendering before it returns. Isn't multithreading fun!