Drawing

Inside Macintosh: OpenDoc Class Reference / Part 2 - Types and Constants

Drawing
This section describes the types and constants used when parts draw themselves.

Basic Imaging
The following types and constants are used frequently in drawing operations. Types marked [M] are specific to the Mac OS platform.

ODGraphicsSystem
A 16-bit value specifying a native platform graphics system. Every graphics system supported by OpenDoc should be identified by a unique ODGraphicsSystem value. These values are used by transform objects and shape objects to tag graphics-system-specific data.
Constants of this type

kODNoGraphicsSystem
No graphics system.
kODQuickDraw
The QuickDraw graphics system.
kODQuickDrawGX
The QuickDraw GX graphics system.

ODPlatformCanvas
A 32-bit value identifying a platform-specific or graphics-system-specific drawing environment.
ODPlatformPrintJob
A 32-bit value identifying a platform-specific or graphics-system-specific print job data structure.
ODPlatformShape
A 32-bit value identifying a graphics-system-specific shape. The format of the shape data is unspecified, and it must be tagged with an ODGraphicsSystem value (page 883) to identify the graphics system to which it belongs. Given the pair (ODPlatformShape, ODGraphicsSystem), it is always possible to identify the exact type of the shape data.
ODgxShape [M]
A 32-bit value representing a QuickDraw GX shape object; this type is identical to the QuickDraw GX type gxShape.
ODRgnHandle [M]
A 32-bit value representing a handle to a QuickDraw region; this type is identical to the QuickDraw type RgnHandle.

Geometry
The following types and constants represent geometric structures, such as distances, positions, bounding rectangles, and shapes. At runtime, shapes are usually represented by objects of the ODShape class (page 629), but can be accessed and stored in the forms described here.

ODCoordinate
A 32-bit value representing a spatial coordinate in a window or document. By default, OpenDoc represents a coordinate with 16 integer bits and 16 fractional bits, which is identical to a value of the ODFixed type (page 873). You can partition the bits of an ODCoordinate value in any way, provided that you shift the values appropriately when passing information outside OpenDoc. (If you are using a graphics system that handles arbitrary transformations, such as QuickDraw GX, you can do this automatically by assigning a scaling factor to your internal transform.)
ODPoint
A structure representing a spatial point in a window or document.
            struct ODPoint {
               ODCoordinate   x;
               ODCoordinate   y;
            };
Field descriptions

x
The x coordinate.
y
The y coordinate.

In two-dimensional imaging models (the only imaging models that currently exist for OpenDoc), a point is represented as a pair of ODCoordinate values (page 885).

On the Mac OS, this type is identical to the QuickDraw GX gxPoint type. Developers who are accustomed to QuickDraw should note that the x coordinate appears first and that the coordinates are fixed-point numbers.
ODRect
A structure representing a rectangle whose sides are aligned with the axes of the current coordinate system.
            struct ODRect {
               ODCoordinate   left;
               ODCoordinate   top;
               ODCoordinate   right;
               ODCoordinate   bottom;
            };
Field descriptions

left
The left coordinate of the rectangle.
top
The top coordinate of the rectangle.
right
The right coordinate of the rectangle.
bottom
The bottom coordinate of the rectangle.

A rectangle is represented as four ODCoordinate values (page 885). By convention, a rectangle does not include its bottom or right edge; this makes it easier to have adjacent yet nonoverlapping rectangles.

On the Mac OS, this type is identical to the QuickDraw GX gxRect type. Developers who are accustomed to QuickDraw should note that the left coordinate comes before the top one, and that the right coordinate comes before the bottom one.
ODContour
A closed loop of three or more points connected by straight edges. A contour is represented as a 32-bit signed value, indicating the number of points in the contour, followed by the specified number of ODPoint structures (page 885) representing the individual points.

The order of points in a contour is significant: for a left-oriented coordinate system like QuickDraw, points arranged in a clockwise order represent a positive area, whereas in the opposite order they represent a negative area or hole (in a right-oriented coordinate system such as OS/2, the reverse is true).

An ODContour structure exists only as a component of an ODPolygon structure (page 886).
ODPolygon
A structure of type ODByteArray (page 877) representing a two-dimensional shape composed of one or more contours. Polygons with multiple contours may be composed of disjoint pieces or may have interior holes. The buffer of a polygon byte array contains a 32-bit signed value, indicating the number of contours in the polygon, followed by the specified number of ODContour structures (page 886) representing the individual contours.

The ODPolygon structure is the platform-independent interchange format for all shapes, including frame shapes.

Shapes and Transforms
The following types and constants relate to shapes and transforms.

ODGeometryMode
An enumeration specifying the geometry modes of a shape object, indicating whether the shape is required to maintain its geometric (polygonal) representation. Shapes (such as frame shapes) that are stored persistently in storage unit values must be stored as polygons. A shape loses its polygonal representation if it is combined with (that is, unioned with, subtracted from, or intersected with) a shape that does not have polygonal representation.
Constants of this type

kODLoseGeometry
The shape does not need to use a polygon to describe its geometric representation. The polygonal representation can be discarded in order to optimize speed, at the expense of accuracy and persistent storage capability. A facet's clip shape will generally have this mode.
kODNeedsGeometry
The shape must maintain its polygonal representation. A facet's frame shape and used shape will have this mode because they are stored persistently in polygonal form.
kODPreserveGeometry
The shape must maintain its polygonal representation for as long as possible. This is the default value.

ODMatrix
A structure representing a platform-independent coordinate transformation.
            struct ODMatrix {    // Note: Rightmost column 
               ODFixed m[3][3];  //    of matrix m contains
   
            };                   //    ODFract elements.
Field descriptions

m
A 3-by-3 transform matrix of fixed-point numbers.

Although the transform matrix in the m field is declared to be of the ODFixed type (page 873), the rightmost column of the matrix (elements m[0][2], m[1][2], and m[2][2]) are actually of the ODFract type (page 874).

A transform matrix can be used for translation, scaling, skewing, rotation, or any combination. See the ODTransform class description (page 762) for more details.

The ODMatrix structure is equivalent to the QuickDraw GX gxMapping structure.
ODTransformType
A 16-bit value used to specify the type of transformation specified by a transform object.
Constants of this type

kODIdentityXform
Identity (no-op) transform.
kODLinearTranslateXform
Scale, rotate, skew, and translation.
kODLinearXform
Scale, rotate, and skew.
kODPerspectiveXform
Perspective transformation, which applies a 3D or distortion effect.
kODScaleTranslateXform
Scale and translation.
kODScaleXform
Pure scale.
kODTranslateXform
Pure translation (offset).