control

CD - Canvas Draw

previous page next page

System

char* cdVersion(void); [in C]
cdVersion() -> (version: string) [in Lua]

Returns the current version number of the library. The string with the version number has a format "major.minor.build". For instance, the string "2.1.3" has number 2 as the main (major) version number, 1 as the secondary (minor) version number, and 3 as the build number. The major version number represents a change in the structure or behavior of functions; the minor version number represents one or more new drivers and functions added to the library; and the build version number represents one or more corrected bugs.

Control

cdCanvas *cdCreateCanvas(cdContext* ctx, void *data); [in C]
cdCreateCanvas(ctx: number, data: string or userdata) -> (canvas: canvas_tag) [in Lua]

Creates a CD canvas for a virtual visualization surface (VVS). A VVS may be the canvas of a user-interface window, the page of a document sent to a printer, an offscreen image, the clipboard, a metafile, and so on. To create the canvas, it is necessary to specify the driver in which each canvas is implemented.

The driver is set by the driver variable with additional information provided in the data parameter. Even though it is possible to create more than one canvas with the same driver/data pair, this is not recommended, and its behavior is not specified. Each canvas maintains its own features.

In case of failure, a  NULL value is returned. The following predefined drivers are available:

Window-Base Drivers

Device-Based Drivers

Memory-Based Drivers 

File-Based Drivers 

  • CD_CGM = Computer Graphics Metafile ISO (cdcgm.h).
  • CD_DGN = MicroStation Design File (cddgn.h).
  • CD_DXF = AutoCad Drawing Interchange File (cddxf.h).
  • CD_EMF = Microsoft Windows Enhanced Metafile (cdemf.h). Works only in MS Windows systems.
  • CD_METAFILE = Metafile Canvas Draw (cdmf.h).
  • CD_PS = PostScript File (cdps.h).
  • CD_WMF = Microsoft Windows Metafile (cdwmf.h).

cdCanvas* cdCreateCanvasf(cdContext *context, char* format, ...); [in C]
[There is no equivalent in Lua]

Same as cdCreateCanvas, used in the case that the parameter data is a string composed by several parameters. This function can be used with parameters equivalent to the printf function from the default C library.

void cdKillCanvas(cdCanvas *canvas); [in C]
cdKillCanvas(canvas: canvas_tag) [in Lua]

Destroys a previously created canvas.

int cdActivate(cdCanvas *canvas); [in C]
cdActivate(canvas: canvas_tag) -> (status: number) [in Lua]

Activates a canvas for drawing. There is no explicit  cdDeactivate. When a new canvas is activated, the current one is deactivated (there can be only one active canvas at a given moment). The function returns a status, CD_OK or CD_ERROR, indicating whether the target canvas was successfully created or not. A NULL canvas can be activated, but any function call will cause an invalid memory access.

cdCanvas* cdActiveCanvas(void); [in C]
cdActiveCanvas() -> (canvas: canvas_tag) [in Lua]

Returns the active canvas. Returns NULL if there is no active canvas.

cdContext* cdGetContext(cdCanvas *canvas); [in C]
cdGetContext(canvas: canvas_tag) -> (ctx: number) [in Lua]

Returns the context of a given canvas, which can be compared with the predefined contexts, such as "CD_PS".

int cdContextCaps(cdContext* ctx); [in C]
cdContextCaps(ctx: number) -> (caps: number) [in Lua]

Returns the resources available for that context. To verify if a given resource is available, perform a binary AND (&) with the following values (in Lua, the values must be summed):

CD_CAP_FLUSH
CD_CAP_CLEAR
CD_CAP_PLAY
CD_CAP_YAXIS - The Y axis has the same orientation as the CD axis.
CD_CAP_CLIPAREA
CD_CAP_CLIPPOLY - Usually is not implemented.
CD_CAP_MARK - Marks are implemented directly in the driver (they are usually simulated).
CD_CAP_RECT - Rectangles are implemented directly in the driver (they are usually simulated).
CD_CAP_VECTORTEXT - Vector text is implemented directly in the driver (it is usually simulated).
CD_CAP_IMAGERGB
CD_CAP_IMAGERGBA - If this is not implemented, but cdGetImageRGB is, then it is simulated using cdGetImageRGB and cdPutImageRGB.
CD_CAP_IMAGEMAP
CD_CAP_GETIMAGERGB
CD_CAP_IMAGESRV - Usually is only implemented in contexts of window graphics systems (Native Window and IUP).
CD_CAP_BACKGROUND
CD_CAP_BACKOPACITY
CD_CAP_WRITEMODE
CD_CAP_LINESTYLE
CD_CAP_LINEWITH
CD_CAP_WD - Functions of world coordinates are implemented directly in the driver (they are usually simulated).
CD_CAP_HATCH
CD_CAP_STIPPLE
CD_CAP_PATTERN
CD_CAP_FONT
CD_CAP_FONTDIM - If not defined, the function is implemented using an internal heuristics of the library.
CD_CAP_TEXTSIZE - If not defined, the function is implemented using an internal heuristics of the library.
CD_CAP_TEXTORIENTATION - Usually is not implemented.
CD_CAP_PALETTE - Usually is only implemented in contexts of window graphics systems (Native Window and IUP).

void cdFlush(void); [in C]
cdFlush() [in Lua]

Has a different meaning for each driver. It is useful to send information to buffered devices and to move to a new page or layer. In all cases, the current canvas attributes are preserved.

void cdClear(void); [in C]
cdClear() [in Lua]

Cleans the active canvas using the current background color. This action is interpreted very differently by each driver. Many drivers simply draw a rectangle with the current background color. It is NOT necessary to call cdClear when the canvas has just been created, as at this moment it is already clean. Most file-based drivers do not implement this function.

int cdSimulate(int mode); [in C]
cdSimulate(mode: number) -> (old_mode: number) [in Lua]

Activates the simulation of one or more primitives and clipping for the active canvas. It is ignored for the canvas in the ImageRGB context, for in this case everything is already simulated. It also has no effect for primitives that are usually simulated. It returns the previous simulation, but does not include primitives that are usually simulated. The simulation can be activated at any moment. For instance, if a line simulation is required only for a situation, the simulation can be activated for the line to be drawn, and then deactivated.

ATTENTION: Using the clipping simulation causes some primitives to be internally simulated, such as  Polygons, Arcs and Sectors. Be careful when activating the clipping simulation.

See in the Simulation sub-driver the information on how each simulation is performed.

To activate a given simulation, perform a binary AND (&) with the following values (in Lua, the values must be summed):

CD_SIM_NONE - Deactivates all kinds of simulation.
CD_SIM_CLIPAREA
CD_SIM_CLIPPOLY
CD_SIM_TEXT
CD_SIM_MARK
CD_SIM_LINE
CD_SIM_RECT
CD_SIM_ARC
CD_SIM_POLYLINE
CD_SIM_BOX
CD_SIM_SECTOR
CD_SIM_POLYGON
CD_SIM_WD
CD_SIM_VECTORTEXT
CD_SIM_ALL - Activates all simulation options.
CD_SIM_LINES - Combination of CD_SIM_LINE, CD_SIM_RECT, CD_SIM_ARC and CD_SIM_POLYLINE.
CD_SIM_FILLS - Combination of CD_SIM_BOX, CD_SIM_SECTOR and CD_SIM_POLYGON.
CD_SIM_CLIP - Combination of CD_SIM_CLIPAREA and CD_SIM_CLIPPOLY.

cdState* cdSaveState(void); [in C]
cdSaveState() -> (state: state_tag) [in Lua]

Saves a state of attributes in the active canvas, returning it. The memory allocated for this will only be liberated with a call to cdRestoreState. It does not save callbacks, polygon creation states (begin/vertex/vertex/...) and the palette.

void cdRestoreState(cdState* state); [in C]
cdRestoreState(state: state_tag) [in Lua]

Returns the attribute state of the active canvas. The memory allocated by the cdSaveState function is liberated and the pointer is no longer valid. It can be used between canvases of different contexts.

void cdSetAttribute(char* name, char* data); [in C]
cdSetAttribute(name, data: string) [in Lua]

Modifies a customized attribute directly in the driver of the active canvas. If the driver does not have this attribute, the call is ignored.

void cdSetfAttribute(char* name, char* format, ...); [in C]
[There is no equivalent in Lua]

Same as cdSetAttribute, used for the case in which the parameter data is a string composed by several parameters. It can be  used with parameters equivalent to those of the printf function from the default C library.

char* cdGetAttribute(char* name); [in C]
cdSetAttribute(name: string) -> (data: string) [in Lua]

Returns a customized attribute from the driver of the active canvas. If the driver does not have this attribute, it returns NULL.

Metafile Interpretation

int cdPlay(cdContext* ctx, int xmin, int xmax, int ymin, int ymax, void *data); [in C]
cdPlay(ctx, xmin, xmax, ymin, ymax: number, data: string) -> (status: number) [in Lua]

Interprets the graphical contents (primitives and attributes) in a given driver and calls equivalent functions of the CD library using the active canvas. The primitives are generated inside the region defined by the given coordinates. If xmin, xmax, ymin and ymax are 0, the primitives will be generated with their coordinates having the original values in the file. Only some drivers implement this function.

Drivers available:

  • CD_CLIPBOARD = Clipboard, data is ignored. Works only in the Motif, MS Windows and Macintosh systems.
  • CD_WMF = Windows Metafile, data is a char* for the string ''filename''. Works only in the MS Windows system.
  • CD_EMF = Windows Enhanced Metafile, data is a char* for the string ''filename''. Works only in the MS Windows system.
  • CD_CGM = Computer Graphics Metafile ISO, data is a char* for the string ''filename''.
  • CD_METAFILE = Metafile Canvas Draw, data is a char* for the string ''filename''.

int cdRegisterCallback(cdContext *ctx, int cb, int(*func)(cdContext *driver, ...)); [in C]
cdRegisterCallback(ctx, cb: number, func: function) -> (status: number) [in Lua]

Used to customize the behavior of the  cdPlay function. If you register a known callback function, it will be called during the processing loop of cdPlay. There is a default callback common to all implementations of cdPlay, CD_SIZECB. Its definition is "int cdResizeCB(cdContext *driver, int width, int height, double mm_width, double mm_height)", and it returns the size of the image in the file before any function in the CD library is called, so that you can call the  cdPlay function without an active canvas and create the canvas inside the callback. It works as a  cdGetCanvasSize function. If the callback returns 1, the cdPlay function is aborted. The callback identifiers of a given driver must be in the public inclusion file relative to that driver, with prefix "CD_XX_CB_", where XX identifies that driver.

previous page start next page