Home -> IRenderer -> StartNewFrame
Description
The renderer usually has two concurrent processes running: the build phase and the draw phase. Calling the StartNewFrame waits for the current draw process to complete, then rolls the build state over into the draw state and starts a new frame drawing. Once a frame has been submitted for drawing, the application cannot modify it in any way. Any attempts to modify the state of any objects only affect the build state, which will be used to define the contents of the next frame which is drawn after the StartNewFrame method is called again.
Important
When the renderer is first created, it starts in build mode. This means scene content can be set and modified straight away. The first time StartNewFrame is called, a new frame will be submitted for drawing.
Warning
Note that no state changes are permitted while this method is being called, on any objects which have been created by this renderer instance. Although all objects provided by the renderer are thread safe under normal operation, a call to the StartNewFrame method must be performed exclusively. External synchronization to ensure that no other operations are in progress or are initiated when this method is being called is the responsibility of the application. The renderer SDK provides the ReadWriteMutex type to assist with synchronization. Please see the section on the Threading Model for more information.
Important
If the previous frame has not finished drawing yet, this method will block until the frame has been fully rendered. If your application has a fixed set of changes that must make it into each frame, where no new frames can be drawn until all the changes are performed, and no more changes are required once they are complete, it is sufficient to call StartNewFrame after each set of changes to advance the drawing process. If however your application has updates that run independently from the draw process, and merely need to be submitted as transactions which make it into whichever frame is currently being drawn, it is recommended to call WaitForDrawComplete first to ensure that all pending draw tasks have been completed. This will ensure that StartNewFrame blocks for the minimal amount of time, which is important as no render state changes can be performed while this method is executing.
Usage
void StartNewFrame();