From RAD Studio API Documentation
Jump to: navigation, search


function BeginScene(AClipRects: PClipRects = nil; AContextHandle: THandle = 0): Boolean;


bool __fastcall BeginScene(PClipRects AClipRects = (PClipRects)(0x0), NativeUInt AContextHandle = (NativeUInt)(0x0));


Type Visibility Source Unit Parent
function public
FMX.Graphics TCanvas


Notifies the TCanvas object that the drawing can begin.

Call BeginScene before drawing on the TCanvas.

To end the drawing session, call EndScene.

If an application has called BeginScene and BeginScene returns True, then the application must call EndScene. That is, the recommended call pattern should look like this:

if Canvas.BeginScene then
  try   //drawing image operations

Each time the TCanvas object calls BeginScene and BeginScene returns True, the value of the BeginSceneCount property is increased by one. Each time the TCanvas object calls EndScene, the value of the BeginSceneCount property is decreased by one. BeginScene uses BeginSceneCount to guaranty that the TCanvas object has no more than one initialized drawing at any moment.

Tip: Notice that calling BeginScene in the OnPaint event handlers has no effect, because BeginScene is called before the OnPaint event handler runs. This guarantees that painting always occurs in OnPaint without requiring extra and probably unexpected code to allow drawing to have an effect.
Note: TCanvas and all subclasses have support for multi-threaded environments, but does not support simultaneous execution of Canvas instances. This means that when a Canvas calls BeginScene, the execution of the code inside this BeginScene...EndScene section blocks any other thread that attempts to process drawing, including drawing on other canvases. Write BeginScene...EndScene blocks as short as possible to avoid blocking other threads.

See Also