FMX.Graphics.TCanvas.BeginScene

From RAD Studio API Documentation
Jump to: navigation, search

Delphi

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

C++

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

Properties

Type Visibility Source Unit Parent
function public
FMX.Graphics.pas
FMX.Graphics.hpp
FMX.Graphics TCanvas

Description

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
    Canvas.xxx   //drawing image operations
    ...
  finally
    Canvas.EndScene;
  end;

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