Render of graphics modules is allowed to be asynchronous and for performance reasons this is usually the case. This has implications for handling capturing of canvas. All kinds of off-screen rendering inside the graphic module is handled by the graphic module in whatever way it sees fitting. If the game scripts desire though to obtain a screenshot for example the data crosses the influence sphere of the graphic module. For this reason capturing a canvas has to be done using deCaptureCanvas.
Capturing using this class is a two-phase process. First and formost you can create and store a capture canvas to use it only when needed. It is not required to time the creation of capture canvas since capturing is only started if all requirements are set. To start a capture set the canvas view you want to capture and the image resource to store the captured image into. Can can freely define the format (component count, bit count and size) of the image. The graphic module adjusts the captured image to your wishes. Once you are ready use SetCapture(true). The graphic module is going to capture the image of the canvas during the next frame rendering. This delay is required since the graphic module is usually still occupied rendering the current frame and does not know about the capture request until the next frame starts. You have then to wait for the result to be ready which is usually one frame later. You know when the capture is finished when GetCapture() turned false again. Once this is the case you can use the image for whatever you need it.
The following code snippet shows the basic flow:
// during frame update called by the game engine // if the capturing finished if not captureRequest.getCapture() ) // do something with captureRequest.getImage() end // do your frame update // do we have a capture request? if doCaptureCanvas // start capture canvas captureRequest.setCanvas( canvasToCapture ) captureRequest.setImage( canvasToCapture.getWidth(), canvasToCapture.getWidth(), 3, 8 ) captureRequest.setCapture( true ) end
The DragonScript module simplifies this process of creating a screenshot by providing the screenshot creator class. You can use it like this:
// during initialization time var ScreenshotCreator screenshotCreator = ScreenshotCreator.new() screenshotCreator.setConsole( gameConsole ) // for logging purpose // during frame update called by the game engine screenshotCreator.update() // to request a screenshot somewhere in the game scripts screenshotCreator.takeScreenshot() // once done the screenshit will be saved as <prefix>date-time<suffix>.