Graphics Environment: 9 Graphics Paths

| Up: GEOS SDK TechDocs| Up | Prev: 8 Graphics Strings | Next: 10 Working With Video Drivers 
GrBeginPath(), GrEndPath(), GrCloseSubPath(), GrSetStrokePath(), GrGetPathBounds(), GrTestPointInPath(), GrGetPathPoints(), GrGetPathRegion(), GrGetPath(), GrSetPath(), GrGetPathBoundsDWord(), GrTestPath()

A path is a data structure which describes a route across a graphics space. Normally, applications use the path to specify an arbitrary screen area, defining a path that describe's the area's borders. Like a GString, a path is created by calling an appropriate initiation routine followed by a series of drawing commands.

Paths don't have to be continuous. An unconnected path is said to be made up of more than one path element.

Paths can be created by taking the intersection or union of two or more paths. In this case, the paths which are combined to make the resulting path are called sub-paths .

Paths are normally used to describe regions. However, regions are basically bitmaps, whereas paths are described in terms of the standard coordinate space. Thus, while regions don't scale well at all, it is possible to scale a path perfectly, then use the transformed path to more correctly compute the desired region. If this comparison sounds similar to that between bitmap- and outline- based fonts, it should. The "outline" of an outline-based font character is, in fact, a specialized form of path.

Paths are also used to describe clipping regions. It is possible to combine any path with a window's clipping region to further restrict the clipping area. Thus it is possible to clip to an ellipse or to a Bézier curve, or even to use text as a clipping region.

When constructing a path, you should keep in mind what it will be used for. If the path is to be filled using the winding rule, it is important that all edges go the correct direction. The winding rule algorithm assumes that the region is described by edges that go around it counterclockwise. Edges going clockwise describe hollows. The odd/even fill rule will work independently of path direction. See the Drawing Shapes chapter for more information about winding rules.

Both the winding and odd/even fill rules demand closed path elements. If any path elements are not filled, the routine will treat them as if they were, connecting the ends of each open path element with a straight line.

It is also possible to alter an existing path by combining it with another. The new path thus formed preserves both paths. If drawn, both paths will appear. If the path is filled or used as a clipping region, the geode can specify how the regions described by the paths should be combined, whether the intersection or union should be taken. Any number of paths can be combined in this manner.

GrBeginPath() signals that the geode is about to start describing a path. All drawing commands directed at the GState will go into constructing the path until GrEndPath() is called. GrBeginPath() is also the routine used to combine a path with an existing path. Calling GrBeginPath() when already constructing a path signals that further graphics commands should describe a new path to be combined with the existing one. The new path can either replace the existing one or combine to find the intersection or the union.

GrCloseSubPath() closes the current path element, adding a straight line segment from the current position to the starting point if necessary.

GrGetPathBounds() returns the bounding coordinates of a rectangle that completely encloses the current path. GrTestPointInPath() tests whether a passed point falls within the current path. GrGetPathPoints() returns all the points along a path in the order visited. GrGetPathRegion() returns the region defined by the path. GrGetPathBoundsDWord() returns the bounds of the path and works in a 32-bit graphics space. If you just want to know whether or not a given path exists, then call GrTestPath() , passing the GetPathType GPT_CURRENT.

GrSetStrokePath() replaces the current path with the one that would result from "stroking" (drawing) the current path with the current line attributes. For example, if the current line style is a dotted line, the result will most likely be a set of many skinny regions. At this time, stroke paths cannot be used for clipping purposes. However, geodes can still draw and fill these paths.

Paths can be drawn or filled using the GrDrawPath() and GrFillPath() commands. For more information about these routines, see the Drawing Shapes chapter.

GrGetPath() retrieves the handle of a block containing the path's data. You may pass this handle to GrSetPath() and thus copy a path to another GState.

| Up: GEOS SDK TechDocs| Up | Prev: 8 Graphics Strings | Next: 10 Working With Video Drivers