Canvas 2½D

(Copyright Philip Quaife April 2007)

Version 1.0


This widget is designed to be 100% compatible to with the Tk canvas widget but allowing extensions to handle 3D graphics, scaled and rotated images and text, gradient fills.

with the API being written entirely in TCL, it allows the application developer the ability to create new canvas commands and canvas item types.

Package name

The package can be loaded by two different names.

  1. newcanvas
    This overrides the Tk canvas command .
  2. glcanvas
    This creates the command glcanvas in the global namespace.

Example 1

	package require newcanvas
	pack [canvas .c] -expand 1 
	.c create text 100 100 -text "I Am a canvas window"

Example 2

	package require glcanvas
	pack [glcanvas .c] -expand 1 
	.c create text 100 100 -text "I Am a glcanvas window"

Using the package name newcanvas can be used to upgrade legacy applications to have a more modern look. This can be called from a start script or from the .wishrc initialisation file.
To run legacy applications from within the new canvas one could use the following interposing script:

	# runlegacy.tcl
	package require newcanvas
	set f  [lindex $argv 0]
	set argv [lrange $argv 1 end]
	source $f

Call the legacy application via the script:

    wish runlegacy.tcl /path/to/legacyapplication.tcl

Coding for both Tk and GlCanvas

To code applications that will work with both version of the canvas widget, you will have to make the canvas items in two stages. The first stage creates the item only using options that are available to the Tk canvas.
The second stage adds the glCanvas enhancements to the created item.

Example 3

	catch {package require newcanvas}
	pack [canvas .c ]
	# Stage 1 create item
	set id [.c create rectangle 0 0 100 100 -fill red]
	# Stage 2 Add Gl extensions 
	catch {.c itemconfigure $id -fill {red red blue blue}}

The above code will add a gradient fill from red to blue to the rectangle if the glCanvas widget is available while still allowing the application to run under the Tk canvas.
The enhancements could also be applied using canvas tags to change multiple items at once.


For the operation of the glCanvas widget, refer to the Tcl/Tk documentation at [1]
This document only outlines the extensions to the Tk canvas widget. All commands not documented here should operate in exactly the same way as the Tk canvas widget. Currently there are some incompatibilites between the the Tk canvas and the GLcanvas widgets. Most of the applications using the glcanvas will not be affected. Some of these incompatibilites will be removed in future releases of the code.

IncompatibilityTypeNewCanvas implimentation difference
pathName create windowPermanentCannot be supported as foreign windows cannot be rendered with the GL context.
This is not a real limitation as the pathName is powerful enough to create subwindow regions that behave like native ones.
Embedded windows would need a C extension that provided a pixmap to render their contents into. This pixmap could then be placed into the canvas window as an image.
pathName create bitmapTemporaryDoes not process bitmap items presently
pathName find enclosingTemporaryDoes not reject items that have coordinates outside the box
pathName itemconfigure -stippleTemporary Line and polygon Stippling is not implemented
pathName Temporary ?
canvas 'C' extensions PermanentCanvas C extensions cannot be used with th glCanvas. To use them requires a 'C' interface that allows the extension to render to a pixmap and then display the pixmap on the glCanvas.

New Features

Canvas Widget commands

pathName rotate tagid deltaangleRotates all items matching tagid by an additional amount specified by deltaangle
This updates the items property -rotation instead of the objects coordinates
pathName create group coordlist -groupname nameCreates a new group item that other items can be attached to. This option is seperate from any tags an item may have.
pathName create lines x1 y1 x2 y2 ... x1 y1 x2 y2Creates a set of disjoint lines, each set of four coordinates is a separate line.
pathName create points x1 y1 ... x1 y2Creates a set of points, each one specified by an x and y coordinate.
pathName create shape coordlist -shapes shapenamesPlaces a previously defined shapes named in the list shapenames at the cordinates specified
The same shapenames may be added more than once. Allowing shapes to be used as templates.
pathName create triangle coordlist -groupname nameCreates a new group item that other items can be attached to. This option is seperate from any tags an item may have.
pathName create plane coordlistCreates a new plane item
pathName create cube coordlist Creates a new cube
pathName create torus coordlistCreates a new torus item
pathName create sphere coordlist Creates a new cube
pathName create pyramid coordlist Creates a new square base pyramid
pathName itemcget tagid option ?value?An optional value passed to cget will update the option specified. This bypasses any canvas update or option processing and is thus much faster
pathName bcube tagidreturns the bounding cube for a set of 3D items.
pathName pickObject x1 y1 xsize ysizeScans a region of the canvas centered at x1,y1 with an area of xsize by ysize and returns a list of all items that are drawn within that area. Items that are grouped return a list with the group item numbers first.
pathName idleupdateSchedule the widget to redraw itself on the next idle update
The following commands will only be used by developers creating their own canvas item types or requiring specialised or optimised 3D facilities.
pathName ~= nameDefines a new GL display list and assigns name to it
pathName ~ nameReturns the GL display list associated with name
pathName ~? nameReturns true if name has a display list assigned to it
pathName getdlist id ?type?Returns the base dlist assocated with id. Type can be one of object colour trfm
pathName teximage texname filenameCreates a texture from the image data stored in the file filename
pathName maketexturefromimage texname imageCreates a texture called texname from the Tk image called image. This command is normally called automatically when the -image argument is specified to a newly created item.
pathName register primname optionvalues bodyDefines a new primative command that will handle requests from the create primname command.
The parameter optionvalues is a list of name value pairs. These define the options and their default value if they are not specified atthe time the create command is called.
pathName extend name args bodyDefines name as a new command to the canvas. This will handle calls to pathName name ...
pathName font fontfamily fontsize fontface ?type?Make the specified font available for use with text items. This is normally called automatically when defining text items
?type? can be one of txf, qfnt, ttf, t1 . Any font files needed are search for using the canvases fontpath configuration option.
pathName glqueryParameter ?size? Queries the GL parameter specified by parameter and returns a list of size floating point values. Size defaults to 1.
The GL_ parameter prefix is not specified to the command.
pathName glenviron + | - | / OPTIONSAdds or removes GL State options to the evironment that is set before the canvas items are drawn.
Items preceded with + are Enabled, items precedded with - are Disabled, items preceded with / are forgotten and retain their state that was last set be a glEnable or glDisable command. The GL_ prefix is not specified.
pathName ??
pathName ??
pathName ?? ??
?? ??
?? ??
?? ??
?? ??
?? ??

Canvas Options


CanvasItem Options

Unlike the Tk canvas the options for an item are not predetermined. Each item type as a set of options that are need to render correctly. Sane defaults are used for options not specified.
Beyond that set of options, the application can attach any named value pair to an item or set of items for use as the developer chooses. These extra options are ignored by the canvas item handlers.

All options after -text are ignored by the text item and are available to the application to read via itemcget and update via itemconfigure. These are typically used in event scripts that are bound to tags. The script can use these extra options to store state information for the selected item.

Each item type that is the same name as the Tk canvas has same options in the glCanvas, the meaning and useage is identical to the Tk canvas. Refer to the Tk canvas documentation for a list of options supported by each item type.

New Item options are described below.
-anchor posAll items have an anchor point. The item will be rotated around its anchor
-translation {absx absy}A translation is applied to the item before it is drawn.
-rotation angleSets the clockwise rotation of the object about it's anchor position in the Z plane, specified in degrees.
-rotationX angleSets the clockwise rotation of the object about it's anchor position in the X plane, specified in degrees.
-rotationY angleSets the clockwise rotation of the object about it's anchor position in the Y plane, specified in degrees.
-scale {scalex scaley}Scaling is applied to the item before it is drawn. Items are scaled around their anchor position
This is different from the canvas scale command as the latter scales the coordinates of the item,
All scaling is relative to the item's anchor position. To be compatible with the Tk canvas any coordinates returned via the coords command will be scaled by the -scale value.
-layer nSets the depth of an object regardless of it's stacking order in the display list. The range is 0 - 100 where 100 is topmost, the default is 50
Raise and Lower will not affect the relationship between items of different layers. The item with the largest layer number will always be on top.
-alpha 0.0-1.0Sets the transparency value for the colour of the object. A value of 1.0 is fully opaque. An alpha value less than 1.0 automatically enables blending
-groupSpecifies the group name to attach the item to. By default it will be the group CanvasItems
-fill colourlistThe colour of an item can be specified as a list. Some items such as rectangles will apply the colour values in sequence to the vertexes that make up their shape. This will create a gradient colour effect.Colours are applied in a clockwise order.
-blend booleanTrue if blending enabled for item. When enabled, items drawn have their colours merged with that of any items already drawn underneath them. It can also antialias lines and text if enabled.
-smooth booleanEnable Antialiasing for polygon,point and and line items. Enabling smoothing automatically enables blending
-widthvalueSpecifies the width of the item in the x dimension
-heightvalueSpecifies the height of the item in the y dimension
-depthvalueSpecifies the depth of the item in the z dimension
-gltexture teximageApply the texture teximage over the top of the image data
-gltexture teximageApply a texture to the interior of the rectangle. teximage must have been defined with the teximage command
-text text
-font {texfont ptsize face}Renders the text using the texture font loaded under the name texfont
If the font cannot be found then a default font is substituted.
-groupname nameDefine a new group called -groupname.
Items can be attached to this group using itemconfigure tagid -group groupname
-convex booleanNon convex polygons must be tessellated before being drawn. This is very slow. Set -convex to true when the coordinates define a regular convex polygon, thus saving the time of performing a redundant tessellation
-dlists {list of GL display list numbers}Renders a list of GL displaylists at the given coordinates.
-shapes {list of defined shape names}Renders a list of predefined shapes. See SHAPES further in the documentation.

Extending the Canvas Widget

New Commands

New Primatives

Back To TCL index