Book Contents Previous Chapter Next Chapter
This chapter describes the fundamental graphics features provided by Magic Cap for package programmers. Before reading this chapter, you should be familiar with viewables and view hierarchies.
Magic Cap defines a set of classes and operations for drawing on the screen. Because most of the items on the screen are objects that are responsible for drawing themselves, you usually won't have to call on Magic Cap directly to draw graphics. Instead, you can usually just rely on the ability of predefined objects to draw themselves.
Magic Cap imposes an x-y coordinate plane and places viewables on that plane. Magic Cap represents points on the coordinate plane with the data type Dot and defines type Box for describing rectangles on the coordinate plane. For more about the geometry used by Magic Cap graphics, see this book's Viewables and Touching chapter.
Every viewable in Magic Cap is drawn by its Draw operation. Drawing occurs when Magic Cap calls viewables' Draw operations to update the screen.
Magic Cap defines class Canvas to provide an environment for drawing and to implement a connection between Magic Cap's micron-based coordinate system and the physical reality of devices. Whenever Magic Cap calls a viewable's Draw operation, it provides a canvas for the viewable object to use when drawing.
When you write your own packages, you'll never have to create a canvas object. There will always be one passed to your viewable's Draw operation. Class Canvas itself is abstract. Magic Cap uses objects of subclasses of Canvas, such as class PixelMap.
In addition to providing a drawing environment for the Draw operation, class Canvas includes various practical operations that can be useful when you're drawing. These include operations for drawing lines, boxes, and paths, for coloring and copying screen pixels, and several other utilities.
Magic Cap defines objects of class Path to represent arbitrary areas on the screen. Paths are constructed by specifying lines and boxes while accumulating the area inside the lines and boxes. The resulting accumulated area forms the path.
When Magic Cap calls a viewable's Draw operation, it passes a path as a parameter. Magic Cap ensures that any drawing performed by the Draw operation is limited to just the area defined by that path - any attempts to draw outside the path are simply ignored. The technique of limiting drawing to a given path is called clipping. For more information about clipping, see the Clipping section of this book's Viewables and Touching chapter.
You can use paths to create and fill complex areas on the screen. To do this, first specify the path with lines and boxes, then use operations of class Canvasto fill the areas on the screen.
Class Path defines operations that you can use to perform functions such as path intersection and difference, as well as operations to perform hit-testing of paths, dots, and boxes. Path objects are usually in use only for a short time. You'll often create a path to use when calling a drawing operation, then destroy the path after the call is made.
Most Magic Cap drawing is done on the communicator screen, and the most common kind of canvas used for drawing on the screen is a pixel map. Magic Cap implements pixel maps as class PixelMap, a subclass of Canvas. Whenever a viewable must draw on the screen, Magic Cap calls the viewable's Draw operation, passing a PixelMap as the canvas to use for drawing.
The pixel map provides a complete environment for mapping the viewable's drawing onto the screen. In particular, the pixel map provides information about the location in memory of the pixels that will be used for drawing and the number of bits per pixel.
You probably won't ever have to call operations of class PixelMap or create your own pixel map objects when you create your own packages.
Magic Cap supports drawing objects in color or gray levels. Every viewable includes two colors, which the viewable's Draw operation can use however it chooses. Most viewables only use one color in drawing, ignoring the second color.
Colors are encoded as 32-bit values. Twenty-four bits of the color are used to specify intensity values for the red, green, and blue components of the color. The remaining eight bits specify a transparency value for the color.
Magic Cap automatically adapts the colors specified for viewables to the capabilities of the screen that is displaying the software. For example, colors automatically appear as dithered gray patterns on screens that can display gray but not color. Every Magic Cap platform provides at least black and white plus two levels of gray (that is, 2 bits per pixel).
This section discusses the graphics features provided by operations of class Canvas.
Class Canvas defines a set of operations that locate a canvas grid point nearest to a given input value. Call GridH or GridV to find the grid point nearest to the given horizontal or vertical coordinate, respectively. You can call GridDot to find the grid point nearest to a given dot. Call GridBox to return the grid point nearest to a given box.
You can call CanvasBounds to get the bounding box for the canvas.
Call OffsetCanvas to move the canvas by changing its origin.
Magic Cap provides several operations you can use to fill areas on the canvas with color. You can call FillBox to draw a box on the canvas in a given color. Call FillLine to draw a line between two given dots at a given thickness.
You can call FillPath to fill a given path with a color. For more information about paths, see the section Paths above.
Call FillMask to fill part of a canvas with a given color, using a given box as a mask that determines which pixels are actually changed. Call FillMaskTile to use a mask that tiles, or repeats, to fill the designated destination box.
Magic Cap defines several operations for drawing images and raw pixels on the canvas. You can call CopyPixels to transfer pixels from a given souce image to the canvas. Call MaskPixels to copy pixels onto the canvas while using a given mask to determine which pixels are actually changed.
You can call CopyPixelsTile to repeat the pixels as a pattern to fill the given destination box. Call MaskPixelsTile to copy pixels using a mask, repeating the mask as necessary to fill the destination box.
Magic Cap defines the FillText operation to draw text onto the canvas. When you call FillText, you pass a pointer to the text to be drawn, the desired location on the canvas, and the text style. For more information about using text in Magic Cap, see this book's Text chapter.
Magic Cap defines a pair of operations that you can use to work with a single pixel at a time. You can call ModifyPixel to change a given pixel to a given color. Call ReadPixel to determine the color of any given pixel on the canvas.
Magic Cap defines various operations that perform high-level drawing on the canvas, allowing you to draw boxes, paths, and other objects. This section describes the high-level drawing calls.
You can call FrameBox to draw a frame at the location of a given box. Call PaintBox to fill the given box with black, or call EraseBox to fill a box with white.
Call InvertBox to invert all the pixels in the given box. You can call HiliteBox to highlight part of a box.
You can call FramePath to draw a frame that traces a given path. Call PaintPath to fill the given path with black, or call ErasePath to fill a path with white.
Call InvertPath to invert all the pixels in the given path.
You can call ScreenCanvas to get the canvas that represents the Magic Cap screen. Call SpecialEffectsCanvas to return the alternate canvas that Magic Cap uses for drawing special effects on the screen.
You can call FillLine to draw a line between two given dots at a given thickness, as described in the Drawing Filled Areas section of this chapter.
This section discusses the graphics features provided by operations of class Path.
The simplest way to create a path is to call NewBoxPath. This operation creates a rectangular path that is described by a given box. Call SetBoxPath to set an existing path to the area described by a given box. You can call SetEmptyPath to empty the path by setting it to include no area.
Magic Cap defines operations that let you easily create specialized paths that aren't rectangular. You can call SetLinePath to create a linear path described by a pair of points. You can call SetOvalPath to make a path defined by a given oval.
In addition to predefined simple and special paths, such as rectangles, lines, and ovals, Magic Cap provides operations that let you create arbitrarily complex paths that you define by drawing lines and boxes. This section describes the operations you can use to create complex paths.
To begin creating a complex path, call OpenPath. Note that OpenPath does not actually create the path object. You must create the path yourself before calling OpenPath. When the path is open, you can construct it by calling AddLine and AddBox to add lines and boxes to the path's description.
When you have finished constructing the path with calls to AddLine and AddBox, call ClosePath to complete the path definition.
Magic Cap defines a set of operations that work with the fundamental geometry and structure of paths. You can call EqualPath to compare two paths and determine if they are equal. Call PathBounds to get a box that encloses the entire path. Call NotEmptyPath to determine if the path encloses any area.
You can call CopyPath to copy another path to the responder path.
Magic Cap provides a set of calls you can use to perform standard set operations on paths. You can call SectPath to compute the intersection of two paths. Call UnionPath to create a path that consists of the union of two paths. Call DiffPath to calculate the difference between two paths. You can call XorPath to create a path consisting of areas that are in one path but not the other.
Once you have defined a path, you can use operations to modify it by shrinking, enlarging, or moving the area covered by the path. You can call InsetPath to change the size of the path by moving its bounds in or out a given amount. Call OffsetPath to move the path and the area it contains a given distance.
Magic Cap provides a pair of operations you can use to perform hit testing on a path. You can call PathBoundsDot to determine if a given dot is bounded by the path. Call PathHitsBox to test whether any part of a given box is contained by the path.
For more information, see the following topics in Magic Cap Class and Method Reference:
class Canvas
operations and attributes:
CanvasBounds CopyPixels CopyPixelsTile EraseBox ErasePath FillBox FillLine FillMask FillMaskTile FillPath FillText FrameBox FramePath GridBox GridDot GridH GridV HiliteBox InvertBox InvertPath MaskPixels MaskPixelsTile ModifyPixel OffsetCanvas PaintBox PaintPath ReadPixel ScreenCanvas
SpecialEffectsCanvas
class Path
operations and attributes:
AddBox AddLine ClosePath CopyPath DiffPath EqualPath InsetPath NewBoxPath NotEmptyPath OffsetPath OpenPath PathBounds PathBoundsDot PathHitsBox SectPath SetBoxPath SetEmptyPath SetLinePath SetOvalPath UnionPath
XorPath
class PixelMap
Book Contents Previous Chapter Next Chapter