====== Scripting Sapphire ====== ===== Window functions ===== ==== ShowWnd ==== You can open the Sapphire 3D renderer window using the following ZeoScript command: Sapphire.ShowWnd ==== ShowWndEx ==== FIXME ==== HideWnd ==== You can close the Sapphire 3D renderer window using the following ZeoScript command: Sapphire.HideWnd ==== ToggleWnd ==== 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. ==== IsShown ==== FIXME ==== GetHWND ==== FIXME ==== EditHF ==== You can open the Sapphire 3D renderer window in heightfield editor mode using the following ZeoScript command: Sapphire.EditHF ==== EditAM ==== You can open the Sapphire 3D renderer window in attributes map editor mode using the following ZeoScript command: Sapphire.EditAM ==== EditAM ==== You can open the Sapphire 3D renderer window in texture map editor mode using the following ZeoScript command: Sapphire.EditTX ==== RenderFrame ==== FIXME ==== ScreenCap ==== 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 To add more formats to the file selection dialog, edit the filter string above. ==== ScreenCap2 ==== FIXME ===== State functions ===== ==== IsPaused ==== FIXME ==== SetPause ==== 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 ==== SetMouseMode ==== 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 ==== GetBrushRadius ==== FIXME ==== SetBrushRadius ==== FIXME ==== RefreshHF ==== FIXME ==== RefreshTX ==== FIXME ===== Camera functions ===== ==== GetPos3dv ==== FIXME ==== GetPosX ==== FIXME ==== GetPosY ==== FIXME ==== GetPosZ ==== FIXME ==== SetPos3d ==== 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. ==== SetElev ==== 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. ==== GetElev ==== FIXME ==== SetAzim ==== 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. ==== GetAzim ==== FIXME ==== LookAt ==== FIXME ===== Settings/configuration functions ===== ==== EditRendererCfg ==== You can open the renderer settings dialog box for Sapphire using the following ZeoScript command: Sapphire.Settings.EditRendererCfg ==== EditHardwareCfg ==== You can open the hardware settings dialog box for Sapphire using the following ZeoScript command: Sapphire.Settings.EditHardwareCfg ===== Help functions ===== ==== OpenWiki ==== You can open a web-browser and automatically navigate to the Sapphire wiki page / userguide using the following ZeoScript command: Sapphire.Help.OpenWiki ===== Multi-threading considerations===== OpenGL is a state engine((...at least OpenGL 1.x and 2.x are state engines. OpenGL 3.x may be a different story.)), 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!//