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.
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 negative 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. |
Example Code
The following code demonstrates 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);
Supported Controls
You can use CanvasStartBatchDraw with canvas controls.
Parameters
| Input | ||
| Name | Type | Description |
| panelHandle | int | Specifier for a particular panel that is currently in memory. You can obtain this handle from functions such as LoadPanel and NewPanel. |
| controlID | int | 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 functions such as NewCtrl and DuplicateCtrl. |
Return Value
| Name | Type | Description |
| nestingDepth | int | 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. |
Additional Information
Library: User Interface Library
Include file: userint.h
LabWindows/CVI compatibility: LabWindows/CVI 4.0 and later
Examples
Refer to the following examples that use the CanvasStartBatchDraw function:
- apps\iconedit\iconedit.cws
Open example - apps\life\life.cws
Open example - userint\canvas.cws
Open example - userint\canvsbmk.cws
Open example