Canvas 2½D

(Copyright Philip Quaife April 2007)

Version 1.0

Overview

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.

Specification

Incompatibility	Type	NewCanvas implimentation difference
pathName create window	Permanent	Cannot 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 bitmap	Temporary	Does not process bitmap items presently
pathName find enclosing	Temporary	Does not reject items that have coordinates outside the box
pathName itemconfigure -stipple	Temporary	Line and polygon Stippling is not implemented
pathName	Temporary	?
canvas 'C' extensions	Permanent	Canvas 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

Comand	Description
pathName rotate tagid deltaangle	Rotates 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 name	Creates 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 y2	Creates a set of disjoint lines, each set of four coordinates is a separate line.
pathName create points x1 y1 ... x1 y2	Creates a set of points, each one specified by an x and y coordinate.
pathName create shape coordlist -shapes shapenames	Places 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 name	Creates a new group item that other items can be attached to. This option is seperate from any tags an item may have.
3D ITEMS
pathName create plane coordlist	Creates a new plane item
pathName create cube coordlist	Creates a new cube
pathName create torus coordlist	Creates a new torus item
pathName create sphere coordlist	Creates a new cube
pathName create pyramid coordlist	Creates a new square base pyramid
MISCELLANEOUS COMMANDS
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 tagid	returns the bounding cube for a set of 3D items.
pathName pickObject x1 y1 xsize ysize	Scans 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 idleupdate	Schedule the widget to redraw itself on the next idle update
ADVANCED COMMANDS The following commands will only be used by developers creating their own canvas item types or requiring specialised or optimised 3D facilities.
pathName ~= name	Defines a new GL display list and assigns name to it
pathName ~ name	Returns the GL display list associated with name
pathName ~? name	Returns 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 filename	Creates a texture from the image data stored in the file filename
pathName maketexturefromimage texname image	Creates 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 body	Defines 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 body	Defines 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 + | - | / OPTIONS	Adds 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

Items

• -scale
• -projection
• -lights

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.

Eg pathName create text 100 100 -text "John Doe" -dbfield full_name -rowid 25 -wobbleandspin random -expire {after 10 seconds}

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.

Option	Description
ALL ITEMS
-anchor pos	All 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 angle	Sets the clockwise rotation of the object about it's anchor position in the Z plane, specified in degrees.
-rotationX angle	Sets the clockwise rotation of the object about it's anchor position in the X plane, specified in degrees.
-rotationY angle	Sets 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 n	Sets 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.0	Sets 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
-group	Specifies the group name to attach the item to. By default it will be the group CanvasItems
-fill colourlist	The 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 boolean	True 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 boolean	Enable Antialiasing for polygon,point and and line items. Enabling smoothing automatically enables blending
3D ITEMS
-widthvalue	Specifies the width of the item in the x dimension
-heightvalue	Specifies the height of the item in the y dimension
-depthvalue	Specifies the depth of the item in the z dimension
IMAGE ITEMS
-gltexture teximage	Apply the texture teximage over the top of the image data
RECTANGLE ITEMS
-gltexture teximage	Apply a texture to the interior of the rectangle. teximage must have been defined with the teximage command
TEXT ITEMS
-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.
GROUP ITEMS
-groupname name	Define a new group called -groupname. Items can be attached to this group using itemconfigure tagid -group groupname
POLYGON ITEMS
-convex boolean	Non 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
CHAIN ITEMS
-dlists {list of GL display list numbers}	Renders a list of GL displaylists at the given coordinates.
SHAPE ITEMS
-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