# CanvasStartBatchDraw

int CanvasStartBatchDraw (int panelHandle, int controlID);

## Purpose

Allows you to increase the drawing performance of the canvas control. In general, use CanvasStartBatchDraw whenever you want to make two or more consecutive calls to canvas drawing functions. Match each call to CanvasStartBatchDraw with a call to CanvasEndBatchDraw.

You can nest calls to CanvasStartBatchDraw.

The following code shows an example of how to incorporate a sequence of drawing operations on the same canvas control into one batch:

CanvasStartBatchDraw (panelHandle, controlID);
CanvasDrawLine (panelHandle, controlID, point1, point2);
CanvasDrawLine (panelHandle, controlID, point3, point4);
CanvasDrawRect (panelHandle, controlID, rect5);
CanvasEndBatchDraw (panelHandle, controlID);

Before LabWindows/CVI performs drawing operations, it invokes certain operating system functions to prepare for drawing on the particular canvas. Without batch drawing, LabWindows/CVI must call these system functions for each canvas drawing operation. With batch drawing, LabWindows/CVI calls the system functions only once for all of the drawing operations between CanvasStartBatchDraw and the matching CanvasEndBatchDraw.

During a batch draw, you can call drawing operations on other canvas controls or call other User Interface Library functions that perform drawing operations or process events. This has the effect of implicitly ending the batch. The next time you call a drawing function on the same canvas, the batch is implicitly restarted.

Failure to properly match CanvasStartBatchDraw and CanvasEndBatchDraw calls can negate the potential performance improvements but does not cause any other ill effects.

Do not access a canvas control from other threads while batch drawing is in effect for the control.

| Note If the ATTR_DRAW_POLICY attribute for the canvas control is VAL_UPDATE_IMMEDIATELY, no update to the screen occurs until you end the batch. Also, changing values of the ATTR_DRAW_POLICY and ATTR_OVERLAP_POLICY attributes during a batch draw has no effect until after you end the batch.

## Parameters

Input
Name | Type | Description
panelHandle | integer | Specifier for a particular panel that is currently in memory. You obtain this handle from LoadPanel, NewPanel, or DuplicatePanel.
controlID | integer | The defined constant, located in the .uir header file, that you assigned to the control in the User Interface Editor, or the ID returned by NewCtrl or DuplicateCtrl.

## Return Value

Name | Type | Description
nestingDepth | integer | Number of calls to CanvasStartBatchDraw (including this call) that have not been matched by calls to CanvasEndBatchDraw. A negative value indicates that an error occurred.
Code | Error Message String
xx | Nesting depth (success)