{{tag>dragonscript graphic canvas ui capture screenshot}}
<WRAP youarehere>
[[:start|Start Page]] >> [[:gamedev|Game Development with the Drag[en]gine]] >> [[gamedev:canvassystem:introduction|Canvas System]] >> **Capture Canvas**
</WRAP>

====== Capture Canvas ======
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 #@LinkApiDocDE2_HTML~classdeCaptureCanvas.html,deCaptureCanvas~@#.

====== Capture Process ======
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 #@LinkApiDocDE2_HTML~classdeCanvasView.html,canvas view~@# you want to capture and the #@LinkApiDocDE2_HTML~classdeImage.html,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:

<code>
// 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
</code>

====== Screenshot Creator (DragonScript) ======
The DragonScript module simplifies this process of creating a screenshot by providing the #@LinkApiDocDEDS2_HTML~classDragengine_1_1Utils_1_1ScreenshotCreator.html,screenshot creator class~@#.  You can use it like this:

<code>
// 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>.
</code>