CaptureToScene - Learn To Code - PlayBASIC Documentation

CaptureToScene

Parameters: NONE

Returns: NONE

     CaptureToScene switches PlayBASIC's rendering behavior to capturing all future graphics drawing requests to the scene buffer, rather than drawing them immediately.

     All types of drawing commands can be captured to the scene buffer, Ie. Dot, Line, Circle, Shapes, Images, Sprites and Text, through to even Maps and polygons.

     So the Scene Buffer is nothing more than a list of drawing requests from the user this update. These drawing requests will stack up until we clear them. Each draw request has certain characteristics like position / image and scene depth. Which you control. Apart from that, the scene buffer is invisible to the user.

     To view the contents of a scene buffer, we need a camera. Cameras are used to translate the contents of the scene buffer to the screen for you. Which Allows you to render the scene/world from any position you like.

      So the scene buffer is used in conjunction with the Camera & World Buffer systems.

FACTS:

     * You control of the Z depth of captured graphical items by using the CaptureDepth command. All captured items will inherit the current captured depth.

     * The Scene Buffer does not empty itself after rendering, Use ClsScene to clear it.

     * The Scene Buffer is internally initialized to about a limit of 10,000 captured items by default. If you capture too many items PlayBASIC will most likely pop a runtime error. To change the cache size use SceneCacheSize command.

Mini Tutorial:

This example first creates a camera in part 1. Then in the second part it redirects all graphics output to PB's scene buffer.

; ============================
;     Part 1 - Create a Camera
; ============================

; create a camera 1.
  CreateCamera 1

; Activate the camera Auto Cls
  CameraCls 1,on

; Set the Cameras Auto CLS colour
  CameraClsColour 1,RGB(0,255,0)


; ============================
;     Part 2 - Capture some graphics to the Scene buffer
; ============================

; Tell PB to now capture all the following GFX
; commands to the scene buffer rather than draw them
;  immediately
  CaptureToScene

; Clear the SceneBuffer
  ClsScene

; Tell PB to assign the following captured graphics command
; a scene  DEPTH of 1
  CaptureDepth 1


; Draw a BLUE circle the Scene
  CircleC 50,50,40,1,RGB(0,0,255)


; Tell PB to assign the following captured graphics command
; a scene  DEPTH of 20
  CaptureDepth 20

; Draw a RED circle the Scene     buffer
  CircleC 70,50,40,1,RGB(255,0,0)


; Draw the camera and whatever it can see
  DrawCamera 1

; Show the user the screen.
  Sync

; wait for a key press, before ending
  WaitKey

When you test this example in PlayBASIC, you'll notice something interesting occurring. While it simply draws two overlapping BLUE and RED circles to the screen, through a camera. If you look carefully, You may have noticed that even while the code renders the BLUE circle before the RED circle. The RED circle is actually drawn behind the BLUE circle.

This occurs because prior to capturing (when we called circle) the circles to the scene buffer, the code sets the Capturing Z depth of the following graphical items, with the CaptureDepth command. If you look closely, the Blue circle is being captured at a Z depth of 1, while the Red circle is being captured at a depth of 50.

Before the camera renders the items in the scene buffer, it first orders them from highest Z depth to lowest. Then renders them in this order (highest to lowest). So items with a higher z depth, will be drawn behind items with a lower Z depth, regardless of what order we capture these drawing requests to the scene buffer in.


Related Info:	CameraBasics \| CaptureDepth \| CaptureToWorld \| CaptureVis \| ClsScene \| CreateCamera \| DrawGFXImmediate \| GetCaptureDepth \| GetCaptureVis \| NewCamera \| SceneCacheSize :