Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

21    Graphics Context Reference

User Interface

Exploring Palm OS®

This chapter describes the graphics context API declared in the header file GcRender.h. It discusses the following topics:

Graphics Context Data Structures and Types
Graphics Context Constants
Graphics Context Functions

For more information on how to work with the graphics context, see Chapter 8, "Drawing," and Chapter 9, "Working with Bitmaps."

Graphics Context Data Structures and Types ^TOP^

GcBitmapHandle Struct ^TOP^

Purpose

The handle to an internal structure that represents the bitmap.

Declared In

GcRender.h

Prototype

typedef struct GcBitmapType *GcBitmapHandle

Fields

None.

See Also

GcDrawBitmapAt(), GcDrawRawBitmapAt(), GcPaintBitmap(), GcLoadBitmap(), GcReleaseBitmap(), FrmGetBitmapHandle()

GcBitmapType Struct ^TOP^

Purpose

Internal structure that stores bitmap data in a format that is most efficient for the rendering system to display on screen.

Declared In

GcRender.h

Prototype

struct GcBitmapType

Fields

None.

See Also

GcLoadBitmap(), GcBitmapHandle

GcColorType Struct ^TOP^

Purpose

Represents a color.

Declared In

GcRender.h

Prototype

typedef struct {
   uint8_t red;
   uint8_t green;
   uint8_t blue;
   uint8_t alpha;
} GcColorType

Fields

red
The red value.
green
The green value.
blue
The blue value.
alpha
The level of transparency, with 0 being transparent and 255 being fully opaque.

See Also

GcInitGradient(), RGBColorType

GcContextType Struct ^TOP^

Purpose

Internal structure that keeps track of the current rendering state.

Declared In

GcRender.h

Prototype

struct GcContextType

Fields

None.

See Also

GcHandle

GcHandle Typedef ^TOP^

Purpose

The handle of a graphics context.

Declared In

GcRender.h

Prototype

typedef struct GcContextType *GcHandle

Fields

None.

Comments

The graphics context keeps track of a current rendering state. You obtain a GcHandle to the graphics context using GcGetCurrentContext(), perform drawing, and then release it using GcReleaseContext() when you are finished.

See Also

GcCreateBitmapContext()

GcGradientType Struct ^TOP^

Purpose

Represents a color gradient.

Declared In

GcRender.h

Prototype

typedef struct {
   float Rdx;
   float Gdx;
   float Bdx;
   float Adx;
   float Rdy;
   float Gdy;
   float Bdy;
   float Ady;
   float R;
   float G;
   float B;
   float A;
   uint32_t _reserved;
} GcGradientType

Fields

Rdx
Change in red per unit step in the horizontal direction.
Gdx
Change in green per unit step in the horizontal direction.
Bdx
Change in blue per unit step in the horizontal direction.
Adx
Change in the alpha transparency value per unit step in the horizontal direction.
Rdy
Change in red per unit step in the vertical direction.
Gdy
Change in green per unit step in the vertical direction.
Bdy
Change in blue per unit step in the vertical direction.
Ady
Change in the alpha transparency value per unit step in the vertical direction.
R
Initial red value.
G
Initial green value.
B
Initial blue value.
A
Initial alpha transparency value.
_reserved
Reserved for future use. Always set to 0.

See Also

GcSetGradient(), GcInitGradient()

Graphics Context Constants ^TOP^

Bitmap Loading Enum ^TOP^

Purpose

Flags to pass to GcLoadBitmap(), GcDrawRawBitmapAt(), and FrmGetBitmapHandle() to specify how the bitmap should be converted when it is loaded.

Declared In

GcRender.h

Constants

kLoadBitmapUnscaled = 0x00000001
Do not scale the bitmap if its density does not match the screen density.
Note that this is different from using WinSetScalingMode() with kBitmapScalingOff. kBitmapScalingOff means use the low-density member of a bitmap family and do not scale it. kLoadBitmapUnscaled simply means do not scale the bitmap but does not affect which bitmap is selected from a bitmap family.
kLoadBitmapMask = 0x00000001
Mask of available flags for loading bitmaps.

GcCapTag Enum ^TOP^

Purpose

Specifies what a line ending looks like.

Declared In

GcRender.h

Constants

kButtCap = 0
There is no special line ending. This is the default.
kRoundCap = 1
The line end is rounded.
kSquareCap = 2
The line end is squared off.
kArrowCap = 3
The line end has an arrow head.

Comments

Figure 21.1 shows the possible line cap endings. To help you better understand the differences between the line endings, the endings are shown for a very thick pen width with the actual line traced in white. As you can see, kButtCap draws the line with no special ending, kRoundCap adds a cap with rounded edges, and kSquareCap adds a cap with squared edges. Caps are drawn outside the bounds of the line.

Figure 21.1  Line cap styles

GcJoinTag Enum ^TOP^

Purpose

Specify what the corner looks like when two lines in a path connect (see Figure 21.2).

Declared In

GcRender.h

Constants

kMiterJoin = 0
The two lines are joined with a square corner as shown on the left side of Figure 21.2. This type of join requires more processing than kBevelJoin and thus should be avoided if unnecessary.
kRoundJoin = 1
The corner is rounded as shown in the center of Figure 21.2. Do not use this if you are drawing curved lines (for example, if you are using GcArc() or GcBezierTo()).
kBevelJoin = 2
The corner is angled as shown on the right side of Figure 21.2. This is the default.

Comments

These constants are part of the rendering state, but they only affect the GcPaint() operation if GcStroke() has been called first.

Figure 21.2  Line joins

See Also

GcSetJoin()

Transform Indexes Enum ^TOP^

Purpose

Index values to use for the matrix array that you pass as a parameter to GcTransform().

Declared In

GcRender.h

Constants

kGcXX = 0
The top left coordinate in the matrix.
kGcYX = 1
The leftmost coordinate in the middle row of the matrix.
kGcXY = 2
The middle coordinate in the top row of the matrix.
kGcYY = 3
The middle coordinate in the second row of the matrix.
kGcXT = 4
The rightmost coordinate in the top row of the matrix.
kGcYT = 5
The rightmost coordinate in the middle row of the matrix.

Comments

These constants define coordinates in the general transformation matrix shown in Figure 21.3.

Figure 21.3  Transformation matrix

The coordinates in this matrix are applied to each point in the current path according to the following equations:

newX = (kGcXX * currentX) + (kGcXY * currentY) + 
kGcXT
newY = (kGcYX * currentX) + (kGcYY * currentY) + 
kGcYT

where (currentX, currentY) represents a point on the path and (newX, newY) represents that point after the transformation has been applied.

Graphics Context Functions ^TOP^

GcArc Function ^TOP^

Purpose

Adds an arc to the current path.

Declared In

GcRender.h

Prototype

void GcArc (
   GcHandle ctxt,
   fcoord_t centerX,
   fcoord_t centerY,
   fcoord_t radx,
   fcoord_t rady,
   float startAngle,
   float arcLen,
   Boolean connected
)

Parameters

ctxt
The graphics context.
centerX
The x coordinate of the arc's center.
centerY
The y coordinate of the arc's center.
radx
The horizontal radius.
rady
The vertical radius.
startAngle
The angle (in radians) from the horizontal radius to the beginning of the arc.
arcLen
The angle (in radians) of the arc itself. This angle must be a positive value.
connected
If true, a line is drawn from the center point to the arc. If false, the arc is drawn without connecting to the center point.

Returns

Nothing.

Comments

Figure 21.4 illustrates how the rendering system computes where to draw the arc. It constructs a template ellipse whose horizontal radius is radx and vertical radius is rady. The starting point of the arc is determine by the startAngle, and the ending point is determined by the arcLen angle. The endpoint of the arc becomes the current point.

Figure 21.4  GcArc example

If connected is true, a straight line is drawn from the current point to the center point and then another straight line is drawn from the center point to the beginning of the arc. If connected is false, a straight line is drawn from the current point to the beginning of the arc unless the current point is the same as the center point. If you don't want the arc connected to any previous drawing, call GcMoveTo() with centerX and centerY before calling this function.

The arc is actually constructed as a series of connected Bezier curves. If you are drawing a stroked path (that is, you want to draw the outline of a shape instead of filling it), do not use kRoundJoin as the line join. Leave the line join setting at the default.

This function adds to the current path in the rendering state; it does not draw to the screen. To draw the current path to the screen, call GcPaint().

Compatibility

Palm OS® Cobalt version 6.0 always draws arcs clockwise (as you are looking at the screen). There is no way to draw a counterclockwise arc; however, one may be added in the future.

See Also

GcArcTo()

GcArcTo Function ^TOP^

Purpose

Computes an arc using a radius and two tangent lines and adds the arc to the current path.

Declared In

GcRender.h

Prototype

void GcArcTo (
   GcHandle ctxt,
   fcoord_t p1x,
   fcoord_t p1y,
   fcoord_t p2x,
   fcoord_t p2y,
   float radius
)

Parameters

ctxt
The graphics context.
p1x, p1y
The point where the two tangent lines intersect. The first tangent is from the path's current point to this point.
p2x, p2y
The end point of the second tangent line. The second tangent line goes from (p1x, p1y) to (p2x, p2y).
radius
The length in coordinates of the arc's radius. Use –1 for this value if you want the arc to be drawn from the current point to (p2x, p2y). Note that in this case, the (p1x, p1y) coordinate must be equidistant from the current point and (p2x, p2y).

Returns

Nothing.

Comments

This function is generally useful for drawing boxes with rounded corners; however, the convenience function GcRoundRect() is more efficient.

As shown in Figure 21.5, this function constructs an arc using two tangent lines and the specified radius. The first tangent line goes from the current point to (p1x, p1y). The second line goes from (p1x, p1y) to (p2y, p2y). Next, the center of the arc is computed by finding the point that is radius distance from the two tangents at a perpendicular angle. Finally, this function adds a path that is a straight line from the current point to the arc's beginning, then the curved arc, and then a straight line from the end of the arc to (p2x, p2y). (p2x, p2y) becomes the current point.

Figure 21.5  GcArcTo() example

Notice that if the radius is very large, the arc may be drawn off screen.

The arc is actually constructed as a series of connected Bezier curves. If you are drawing a stroked path (that is, you want to draw the outline of a shape instead of filling it), do not use kRoundJoin as the line join. Leave the line join setting at the default.

This function adds to the current path in the rendering state; it does not draw to the screen. To draw the current path to the screen, call GcPaint().

Compatibility

Palm OS Cobalt version 6.0 always draws arcs clockwise (as you are looking at the screen). There is no way to draw a counterclockwise arc; however, one may be added in the future.

See Also

GcArc(), GcLineTo()

GcBeginClip Function ^TOP^

Purpose

Begins a block of code that specifies a clipping region.

Declared In

GcRender.h

Prototype

void GcBeginClip (
   GcHandle ctxt,
   Boolean inverse
)

Parameters

ctxt
The graphics context.
inverse
If true, the region that you define will be the inverse of the clipping region. If false, the region you define will be the clipping region.

Returns

Nothing.

Comments

To specify a clipping region, do the following:

  1. Call GcPushState().
  2. Call GcBeginClip().
  3. Call one or more of the path definition functions to specify the clipping region.
  4. Call GcPaint(), which fills the specified region with white.
  5. Call GcEndClip().

After the GcEndClip() call, all drawing is constrained to the region that you defined using this procedure. (If you passed true for the inverse parameter, all drawing is constrained to the region that lies outside of the region you've defined.) The antialiasing value is ignored when the clipping region is specified.

To clear the clipping region, call GcPopState(). Nested clipping regions are not allowed; that is, you cannot call GcBeginClip() twice without calling GcEndClip(). You can, however, define two separate clipping regions in the current rendering state. If you do, the second clipping region is constrained by the first so that the resulting region becomes the intersection of the two regions.

GcBezierTo Function ^TOP^

Purpose

Add a Bezier curve to the path.

Declared In

GcRender.h

Prototype

void GcBezierTo (
   GcHandle ctxt,
   fcoord_t p1x,
   fcoord_t p1y,
   fcoord_t p2x,
   fcoord_t p2y,
   fcoord_t p3x,
   fcoord_t p3y
)

Parameters

ctxt
The current graphics context.
p1x, p1y
The point that controls the angle and direction of the first curve.
p2x, p2y
The point that controls the angle and direction of the second curve.
p3x, p3y
The end point of the line.

Returns

Nothing.

Comments

As shown in Figure 21.6, this function constructs a template consisting of straight lines from the current point to (p1x, p1y) and from (p2x, p2y) to (p3x, p3y). The path it constructs begins at the current point, is tangent to the line that starts at the point, and goes in the direction of (p1x, p1y). The end of the path is at (p3x, p3y). The ending part of the path is tangent to the line from (p2x, p2y) to (p3x, p3y) and heads in the direction of (p2x, p2y). (p3x, p3y) becomes the current point.

Figure 21.6  Bezier curve

If you are drawing a stroked path (that is, you want to draw the outline of the shape instead of filling it), do not use kRoundJoin as the line join. Leave the line join setting at the default.

This function adds to the current path in the rendering state; it does not draw to the screen. To draw the current path to the screen, call GcPaint().

See Also

GcArc(), GcArcTo()

GcClosePath Function ^TOP^

Purpose

Closes the current subpath using a straight line.

Declared In

GcRender.h

Prototype

void GcClosePath (
   GcHandle ctxt
)

Parameters

ctxt
The rendering context containing the path to close.

Returns

Nothing.

Comments

This function draws a straight line from the current point to the point specified by the most recent GcMoveTo() call in the current path. This starting point becomes the current point.

This function adds to the current path in the rendering state; it does not draw to the screen. To draw the current path to the screen, call GcPaint().

GcCommit Function ^TOP^

Purpose

Blocks until all pending drawing operations are completed.

Declared In

GcRender.h

Prototype

void GcCommit (
   GcHandle ctxt
)

Parameters

ctxt
The rendering context to commit.

Returns

Nothing.

Comments

Use this function in the rare circumstances where you need to wait for the rendering system to finish before your application continues.

The rendering system runs in a different process than the application. To avoid IPC overhead, drawing operations are buffered and sent to the rendering system in batches. Because of this, rendering is likely to have not finished, or even started, when a drawing function returns. GcCommit() causes all buffered operations to be sent immediately and then waits for drawing to be completed before it returns.

This function is a performance drain and should be used rarely, only when absolutely necessary.

Note that you do not need to use GcCommit() when drawing to a local bitmap. All drawing to local bitmaps is performed immediately.

See Also

GcFlush()

GcCreateBitmapContext Function ^TOP^

Purpose

Create a rendering context in a given bitmap.

Declared In

GcRender.h

Prototype

GcHandle GcCreateBitmapContext (
   const BitmapType *bitmapP
)

Parameters

bitmapP
The bitmap to use when creating the context.

Returns

A handle to the newly created graphics context or NULL if one cannot be created. See GcHandle.

Comments

Use this function if you want to modify a bitmap.

You pass the GcHandle returned by this function to the drawing operations such as GcBezierTo() and GcLineTo(). When you are finished, you call GcPaint() and then GcReleaseContext().

It is strongly recommended that you never define a color table for bitmaps. Drawing to a bitmap with a color table is much slower than drawing to a bitmap that uses the default color table. If you must define a color table for your bitmap, when you are ready to draw it to the screen, use WinPalette() to change the screen's color table to match your bitmap's color table before you call point the bitmap to the screen. Drawing a bitmap whose color table does not match the color table of the destination is much slower.

Note that the BmpCreate() function creates a single-density bitmap, but the default coordinate system for the context created by GcCreateBitmapContext() is native screen density.

Example

The following example creates a small high-density bitmap containing a red triangle.


BitmapTypeV3 *bmpP; 
GcHandle bitmapContext; 
 
bmpP = BmpCreate(12, 12, 16, NULL, &error); 
bmpP = BmpCreateBitmapV3(bmpP, kDensityDouble,  
       BmpGetBits(bmpP), NULL);  
if (bmpP) { 
   bitmapContext = GcCreateBitmapContext(bmpP); 
   if (bitmapContext) { 
      GcSetColor(bitmapContext, 255, 0, 0, 255); 
      GcMoveTo(bitmapContext, 2, 2); 
      GcLineTo(bitmapContext, 2, 10); 
      GcLineTo(bitmapContext, 10, 10); 
      GcClosePath(bitmapContext); 
      GcPaint(bitmapContext); 
      GcReleaseContext(bitmapContext); 
   } 
} 

See Also

GcReleaseContext()

GcDrawBitmapAt Function ^TOP^

Purpose

Paints the bitmap at the specified coordinates.

Declared In

GcRender.h

Prototype

void GcDrawBitmapAt (
   GcHandle ctxt,
   GcBitmapHandle bitmapHandle,
   const FAbsRectType *srcRect,
   fcoord_t x,
   fcoord_t y
)

Parameters

ctxt
The graphics context.
bitmapHandle
The bitmap. Use FrmGetBitmapHandle() or GcLoadBitmap() to obtain a GcBitmapHandle to a bitmap.
srcRect
Rectangle (see FAbsRectType) that specifies the portion of the bitmap to be drawn to the screen. Pass NULL to draw the entire bitmap. The rectangle must be less than or equal to the bitmap's dimensions and must be expressed in terms of the coordinate system used by the bitmap (that is, the bitmap's density). If you pass a larger rectangle, the bitmap is not tiled.
x, y
Top-left corner of where the bitmap should be drawn.

Returns

Nothing.

Comments

This function defines the path into where the bitmap should be drawn, paints the bitmap, and then clears the current path but no other aspect of the rendering state. Most of the rendering state does not affect this call.

See Also

GcDrawRawBitmapAt()

GcDrawRawBitmapAt Function ^TOP^

Purpose

Paints a bitmap at the specified coordinates.

Declared In

GcRender.h

Prototype

void GcDrawRawBitmapAt (
   GcHandle ctxt,
   const BitmapType *bitmapP,
   const FAbsRectType *srcRect,
   fcoord_t x,
   fcoord_t y,
   uint32_t load_flags
)

Parameters

ctxt
The graphics context.
bitmapP
The bitmap to draw. See BitmapType.
srcRect
Rectangle (see FAbsRectType) that specifies the portion of the bitmap to be drawn to the screen. Pass NULL to draw the entire bitmap. The rectangle must be less than or equal to the bitmap's dimensions and must be expressed in terms of the coordinate system used by the bitmap (that is, the bitmap's density). If you pass a larger rectangle, the bitmap is not tiled.
x, y
Top-left corner of where the bitmap should be drawn.
load_flags
One of the Bitmap Loading constants, which specify whether the bitmap should be scaled.

Returns

Nothing.

Comments

This function creates a GcBitmapHandle for bitmapP, draws it to the screen, and then releases the bitmap handle. You are responsible for loading bitmapP from the database and releasing it when you are done.

See Also

GcLoadBitmap(), GcDrawBitmapAt()

GcDrawTextAt Function ^TOP^

Purpose

Draws text to the screen using the font specified by GcSetFont().

Declared In

GcRender.h

Prototype

void GcDrawTextAt (
   GcHandle ctxt,
   fcoord_t x,
   fcoord_t y,
   const char *text,
   int32_t length
)

Parameters

ctxt
The graphics context.
x
The x coordinate where the text should begin.
y
The y coordinate where the baseline of the text should be. (Letters with descenders will draw below this line.)
text
The text to draw to the screen.
length
The size in bytes of the text string. You can use –1 for this value if text is a null-terminated string.

Returns

Nothing.

Comments

This function generates a path from the supplied text, fills that path, and then clears it. Because this function clears the current path, you must either call GcPaint() to draw any path that you have defined before you add text, or you can call GcPushState() to preserve the drawing and continue after you add the text.

See Also

GcSetFont()

GcEndClip Function ^TOP^

Purpose

Ends the specification of a clipping region.

Declared In

GcRender.h

Prototype

void GcEndClip (
   GcHandle ctxt
)

Parameters

ctxt
The graphics context.

Returns

Nothing.

Comments

After this call, all drawing is constrained to the region that you defined using this procedure. (If you passed true for GcBeginClip()'s inverse parameter, all drawing is constrained to the region that lies outside of the region you've defined.)

To clear the clipping region, call GcPopState(). Nested clipping regions are not allowed; that is, you cannot call GcBeginClip() twice without calling GcEndClip(). You can, however, define two separate clipping regions in the current rendering state. If you do, the second clipping region is constrained by the first so that the resulting region becomes the intersection of the two regions.

GcFlush Function ^TOP^

Purpose

Blocks until all pending drawing operations have been sent.

Declared In

GcRender.h

Prototype

void GcFlush (
   GcHandle ctxt
)

Parameters

ctxt
The rendering context to flush.

Returns

Nothing.

Comments

Use this function in the rare circumstances where you need to wait for the drawing buffer to be empty before your application continues.

The rendering system runs in a different process than the application. To avoid IPC overhead, drawing operations are buffered and sent to the rendering system in batches. Because of this, rendering is likely to have not finished, or even started, when a drawing function returns. GcFlush() causes all buffered operations to be sent immediately and then it returns.

Drawing may not have completed when GcFlush() returns; it simply makes sure all drawing commands have been sent. If you need to make sure that drawing completes before you continue, use GcCommit() instead of GcFlush().

This function is a performance drain and should be used rarely, only when absolutely necessary.

Note that you do not need to use GcFlush() when drawing to a local bitmap. All drawing to local bitmaps is performed immediately.

GcGetBitmapDensity Function ^TOP^

Purpose

Returns the density of a bitmap.

Declared In

GcRender.h

Prototype

uint16_t GcGetBitmapDensity (
   GcBitmapHandle bitmapHandle
)

Parameters

bitmapHandle
The bitmap. Use FrmGetBitmapHandle() or GcLoadBitmap() to obtain a GcBitmapHandle to a bitmap.

Returns

One of the DensityType constants, specifying the density of the bitmap.

Comments

Because the bitmap is scaled when it is loaded into a GcBitmapHandle, the density returned by this function may not be the density set in the bitmap resource. For example, if you have a low-density bitmap and you are drawing to a high-density display, the bitmap is scaled to high density. GcGetBitmapDensity() returns kDensityDouble.

GcGetBitmapDepth Function ^TOP^

Purpose

Retrieves the depth of a bitmap.

Declared In

GcRender.h

Prototype

uint32_t GcGetBitmapDepth (
   GcBitmapHandle bitmapHandle
)

Parameters

bitmapHandle
The bitmap. Use FrmGetBitmapHandle() or GcLoadBitmap() to obtain a GcBitmapHandle to a bitmap.

Returns

The bit depth of a bitmap.

GcGetBitmapHeight Function ^TOP^

Purpose

Returns the height of a bitmap.

Declared In

GcRender.h

Prototype

uint32_t GcGetBitmapHeight (
   GcBitmapHandle bitmapHandle
)

Parameters

bitmapHandle
The bitmap. Use FrmGetBitmapHandle() or GcLoadBitmap() to obtain a GcBitmapHandle to a bitmap.

Returns

Returns the bitmap's height in the bitmap's native coordinates.

Comments

You can use GcGetBitmapDensity() to determine the bitmap's native density and then convert the value returned by GcGetBitmapHeight() to whatever coordinate system you want with the WinConvertCoord() function.

Note that the bitmap is scaled when it is loaded into a GcBitmapHandle, so the density returned by GcGetBitmapDensity() may not be the density set in the bitmap resource. For example, if you have a low-density bitmap of 16 X 16 pixels and you are drawing to a high-density display, the bitmap is scaled to high density. GcGetBitmapDensity() returns kDensityDouble, and GcGetBitmapHeight() returns 32.

GcGetBitmapWidth Function ^TOP^

Purpose

Returns the width of the bitmap.

Declared In

GcRender.h

Prototype

uint32_t GcGetBitmapWidth (
   GcBitmapHandle bitmapHandle
)

Parameters

bitmapHandle
The bitmap. Use FrmGetBitmapHandle() or GcLoadBitmap() to obtain a GcBitmapHandle to a bitmap.

Returns

Returns the bitmap's width in the bitmap's native coordinates.

Comments

You can use GcGetBitmapDensity() to determine the bitmap's native density and then convert the value returned by GcGetBitmapWidth() to whatever coordinate system you want with the WinConvertCoord() function.

Note that the bitmap is scaled when it is loaded into a GcBitmapHandle, so the density returned by GcGetBitmapDensity() may not be the density set in the bitmap resource. For example, if you have a low-density bitmap of 16 X 16 pixels and you are drawing to a high-density display, the bitmap is scaled to high density. GcGetBitmapDensity() returns kDensityDouble, and GcGetBitmapWidth() returns 32.

GcGetCurrentContext Function ^TOP^

Purpose

Creates the graphics context for the current draw window.

Declared In

GcRender.h

Prototype

GcHandle GcGetCurrentContext (
   void
)

Parameters

None.

Returns

A handle to the current context (see GcHandle) or NULL if the graphics context could not be created.

Comments

Use this function to obtain the GcHandle that you pass to all other drawing functions.

If you are drawing to an on-screen window, call this function in response to a frmUpdateEvent. If the draw window is an update-based window, this function returns NULL unless called in response to an update event. If the draw window is a transitional window, you can obtain a graphics handle at any time after the first winResizedEvent is posted; however, it is still a good idea to only draw in response to an update event.


WARNING! Check the return value from this function before passing it to any other drawing functions. Drawing into a NULL graphics context causes the application to crash.

To draw to an off-screen window, create the window first and then call WinSetDrawWindow() before calling GcGetCurrentContext().

To draw into a bitmap, use GcCreateBitmapContext() instead of this function.

You must call GcReleaseContext() when you are finished drawing.

See Also

WinGetActiveWindow()

GcInitGradient Function ^TOP^

Purpose

Creates a gradient for later use with the GcSetGradient() function.

Declared In

GcRender.h

Prototype

status_t GcInitGradient (
   GcGradientType *gradient,
   const GcPointType *points,
   const GcColorType *colors,
   uint32_t num
)

Parameters

gradient
Contains the gradient upon return. See GcGradientType.
points
An array of points (see GcPointType). The number of points is specified in num.
colors
An array of colors (see GcColorType). The number of colors is specified in num.
num
The number of points and colors. Must be either 2 or 3.

Returns

Returns errNone upon success or –1 if the num parameter is invalid.

Comments

This function creates a gradient using the values specified. If you've specified two points and two colors, this function creates a gradient that begins at the first point with the first color and ends at the second point with the color gradually becoming the ending color.

If three values are specified, the gradient works in a triangular fashion with each color starting at its corresponding point and gradually blending into the next color as it approaches that point.

You generally specify a gradient that represents the entire screen and then use a clipping region to constrain the drawing of the gradient to a particular area.

See Also

GcSetGradient(), GcBeginClip()

GcIsBitmapAlphaOnly Function ^TOP^

Purpose

Returns whether the bitmap contains only an alpha channel.

Declared In

GcRender.h

Prototype

Boolean GcIsBitmapAlphaOnly (
   GcBitmapHandle bitmapHandle
)

Parameters

bitmapHandle
The bitmap. Use FrmGetBitmapHandle() or GcLoadBitmap() to obtain a GcBitmapHandle to a bitmap.

Returns

true if the bitmap contains only an alpha channel, or false otherwise.

Comments

Bitmaps containing only an alpha channel are drawn using the current color (set by GcSetColor()) and blended with the destination per the alpha channel.

GcLineTo Function ^TOP^

Purpose

Adds a straight line to the path. The line goes from the current point to the specified point.

Declared In

GcRender.h

Prototype

void GcLineTo (
   GcHandle ctxt,
   fcoord_t x,
   fcoord_t y
)

Parameters

ctxt
The graphics context.
x, y
Ending point of the line to draw. This point becomes the current point.

Returns

Nothing.

Comments

This function adds to the current path in the rendering state; it does not draw to the screen. To draw the current path to the screen, call GcPaint().

See Also

GcClosePath()

GcLoadBitmap Function ^TOP^

Purpose

Converts a bitmap into a format that is most efficient for the rendering system to display on screen.

Declared In

GcRender.h

Prototype

GcBitmapHandle GcLoadBitmap (
   WinHandle win,
   const void *bitmapFileP,
   size_t size,
   uint32_t flags
)

Parameters

win
A handle to the form's window.
bitmapFileP
A pointer to a BitmapType structure or a PNG as loaded from a resource file.
size
The size of the bitmapFileP parameter.
flags
One of the Bitmap Loading constants, which specifies how the bitmap is scaled when it is drawn.

Returns

A GcBitmapHandle in the closest match to the screen density and bit depth.

Comments

You generally don't use this function directly. Instead, use FrmGetBitmapHandle().

For backward compatibility, the BitmapType stores a bitmap's data in big-endian format. This function converts a bitmap into the little-endian format that is used in Palm OS® Cobalt and performs any other conversions that might make it more efficient to draw this bitmap to the screen.

This function makes a copy of the data, so the original bitmap can be deallocated any time after this function is called.

If the bitmap has multiple depths (is a bitmap family), the closest match less than or equal to the current draw window depth is selected from that family and converted. If such a bitmap does not exist, the bitmap with the closest match greater than the draw window depth is used.

Call GcReleaseBitmap() when you are finished with the bitmap.

See Also

GcDrawBitmapAt(), GcDrawRawBitmapAt()

GcMoveTo Function ^TOP^

Purpose

Moves the current point to the coordinates specified.

Declared In

GcRender.h

Prototype

void GcMoveTo (
   GcHandle ctxt,
   fcoord_t x,
   fcoord_t y
)

Parameters

ctxt
The graphics context.
x, y
The point that should become the current point.

Returns

Nothing.

Comments

This function starts a new subpath by moving the current point to the location specified without adding anything to the current path other than this point.

You can think of this function as lifting your pencil and moving it to the specified coordinates. All future drawing starts from this point.

GcPaint Function ^TOP^

Purpose

Paints the current path onto the screen.

Declared In

GcRender.h

Prototype

void GcPaint (
   GcHandle ctxt
)

Parameters

ctxt
The graphics context.

Returns

Nothing.

Comments

This function draws the path as specified by the current rendering state and constrained by the current clipping region. Then it clears the current path. It does not clear any other aspect of the rendering state.

GcPaint() fills the current path with the current color. If you've defined a non-closed path and you call GcPaint(), the result is undefined. To paint just the outline of the path, call GcStroke() before calling GcPaint(). When you call GcStroke(), GcPaint() paints the outline of the current path using the current pen size, cap styles, and line join styles.

GcPaint() is also used to specify the clipping region. If GcPaint() is called in between calls to GcBeginClip() and GcEndClip(), it fills the specified region with white and all subsequent calls to GcPaint() up to the next GcPopState() are constrained to the points within that region.

GcPaintBitmap Function ^TOP^

Purpose

Fills the current path with the specified bitmap.

Declared In

GcRender.h

Prototype

void GcPaintBitmap (
   GcHandle ctxt,
   GcBitmapHandle bitmapHandle
)

Parameters

ctxt
The graphics context.
bitmapHandle
The bitmap to draw to the screen. Use GcLoadBitmap() to obtain a GcBitmapHandle to a bitmap.

Returns

Nothing.

Comments

Think of this function as painting with a bitmap instead of with the current color. It fills the current path with the bitmap, tiling the bitmap if necessary. This function clears the current path but no other aspect of the rendering state. Most of the rendering state does not affect this call.

See Also

GcCreateBitmapContext(), GcDrawBitmapAt(), GcDrawRawBitmapAt(), GcLoadBitmap()

GcPopState Function ^TOP^

Purpose

Restores the previous rendering state.

Declared In

GcRender.h

Prototype

void GcPopState (
   GcHandle ctxt
)

Parameters

ctxt
The graphics context.

Returns

Nothing.

See Also

GcPushState()

GcPushState Function ^TOP^

Purpose

Saves the current rendering state.

Declared In

GcRender.h

Prototype

void GcPushState (
   GcHandle ctxt
)

Parameters

ctxt
The graphics context.

Returns

Nothing.

Comments

The rendering state is specified by calls to most of the other functions in GcRender.h.

The state includes the clipping region and the current path. GcPushState() is often used to preserve the current path before making some other change.

See Also

GcPopState()

GcRect Function ^TOP^

Purpose

Adds a rectangle to the path.

Declared In

GcRender.h

Prototype

void GcRect (
   GcHandle ctxt,
   fcoord_t left,
   fcoord_t top,
   fcoord_t right,
   fcoord_t bottom
)

Parameters

ctxt
The graphics context.
left
x coordinate of the left side of the rectangle.
top
y coordinate of the top of the rectangle.
right
x coordinate of the right side of the rectangle.
bottom
y coordinate of the bottom of the rectangle.

Returns

Nothing.

Comments

The current point is moved to the top-left corner before the rectangle is added to the path. The rectangle is drawn clockwise from the top left corner, resulting in a current point that is the top left corner of the rectangle.

GcRect() is optimized for speed; always use it when you want to draw a square or rectangular region.

This function adds to the current path in the rendering state; it does not draw to the screen. To draw the current path to the screen, call GcPaint().

See Also

GcRoundRect(), GcRectI()

GcRectI Function ^TOP^

Purpose

Adds a rectangle to the path using integer coordinates to define the rectangle.

Declared In

GcRender.h

Prototype

void GcRectI (
   GcHandle ctxt,
   int32_t left,
   int32_t top,
   int32_t right,
   int32_t bottom
)

Parameters

ctxt
The graphics context.
left
y coordinate of the top of the rectangle.
top
y coordinate of the top of the rectangle.
right
x coordinate of the right side of the rectangle.
bottom
y coordinate of the bottom of the rectangle.

Returns

Nothing.

Comments

This function differs from GcRect() in that it takes integer coordinates rather than floating-point coordinates.

GcReflect Function ^TOP^

Purpose

Flips the coordinate system at the specified radius.

Declared In

GcRender.h

Prototype

void GcReflect (
   GcHandle ctxt,
   fcoord_t rad
)

Parameters

ctxt
The graphics context.
rad
The angle of the axis of symmetry.

Returns

Nothing.

Comments

A two-dimensional transformation affects only the drawing functions called after it. If you call this function in the middle of a path definition, it applies only to those points in the path defined after this function is called. If you are creating a stroked path, call this and all other two-dimensional transformations before calling GcStroke().

The axis of symmetry runs through the origin of the screen, which may cause some of the path to be drawn off screen. If you want to reflect the path along an axis that runs through the center of the screen, use GcTranslate() to translate the origin of the screen to the center before calling this function. See GcRotate() for sample code.

See Also

GcScale(), GcTransform()

GcReleaseBitmap Function ^TOP^

Purpose

Releases the memory associated with the bitmap handle.

Declared In

GcRender.h

Prototype

status_t GcReleaseBitmap (
   GcBitmapHandle bitmapHandle
)

Parameters

bitmapHandle
The bitmap to release.

Returns

Always returns errNone.

Comments

Memory is not actually deallocated until all pending drawing operations are complete.

This function does not release a bitmap context. If you've used GcCreateBitmapContext() to create a bitmap that receives drawing operations, use GcReleaseContext() to release it.

See Also

GcLoadBitmap()

GcReleaseContext Function ^TOP^

Purpose

Releases a rendering context.

Declared In

GcRender.h

Prototype

void GcReleaseContext (
   GcHandle ctxt
)

Parameters

ctxt
The rendering context to release.

Returns

Nothing.

Comments

Call this function when you are finished drawing. It pops the current rendering state and releases the memory associated with the graphics context.

If you do not release the graphics context, the user interface will eventually freeze.

See Also

GcCreateBitmapContext(), GcGetCurrentContext()

GcRotate Function ^TOP^

Purpose

Rotates the coordinate system the number of radians.

Declared In

GcRender.h

Prototype

void GcRotate (
   GcHandle ctxt,
   fcoord_t rad
)

Parameters

ctxt
The graphics context.
rad
The number of radians by which to rotate the path.

Returns

Nothing.

Comments

A two-dimensional transformation affects only the drawing functions called after it. If you call this function in the middle of a path definition, it applies only to those points in the path defined after this function is called. If you are creating a stroked path, call this and all other two-dimensional transformations before calling GcStroke().

This function rotates the path around the origin (top-left corner) of the screen. If you want to rotate around some other point, use GcTranslate() to move the origin before you call this function.

Example

The following code draws a square in the center of the screen and rotates it 45 degrees around the center of the screen.


#define DegreesToRadians(x) (fcoord_t)(x * 3.14159/180) 
 
void RotateExample(FormType *pForm) 
{ 
   GcHandle gc = GcGetCurrentContext(); 
   fcoord_t centerX, centerY, radius; 
   fcoord_t extentX = kExtent, extentY = kExtent; 
   fcoord_t startX, startY; 
   RectangleType winBounds; 
 
   if (!gc) return; 
 
   // Compute bounds of window to decide how to center the  
   // square.  
   WinGetWindowBounds(&winBounds); 
   if (winBounds.extent.x) { 
      centerX = ((fcoord_t)(winBounds.extent.x -  
         winBounds.topLeft.x)) / 2; 
      centerY = ((fcoord_t)(winBounds.extent.y -  
         winBounds.topLeft.y)) / 2; 
      startX = centerX - extentX/2; 
      startY = centerY - extentY/2; 
   } else { 
      return; 
   } 
 
   // Translate the origin of the screen to the center point  
   // so that the rest of the transformation is applied from  
   // the center rather than the screen's origin.  
   GcTranslate(gc, centerX, centerY); 
   // Now you need to adjust the starting coordinates  
   // accordingly.  
   startX -= centerX; 
   startY -= centerY; 
   // Set up transformation.  
   GcRotate(gc, DegreesToRadians(45)); 
 
   //Draw the shape and paint it.  
   GcRect(gc, startX, startY, startX + extentX, startY +  
      extentY); 
   GcPaint(gc); 
 
   GcReleaseContext(gc); 
   return; 
} 

See Also

GcReflect(), GcScale(), GcTransform()

GcRoundRect Function ^TOP^

Purpose

Creates a rectangle path with rounded corners.

Declared In

GcRender.h

Prototype

void GcRoundRect (
   GcHandle ctxt,
   fcoord_t left,
   fcoord_t top,
   fcoord_t right,
   fcoord_t bottom,
   fcoord_t radx,
   fcoord_t rady
)

Parameters

ctxt
The graphics context.
left
x coordinate of the left side of the rectangle.
top
y coordinate of the top of the rectangle.
right
x coordinate of the right side of the rectangle.
bottom
y coordinate of the bottom of the rectangle.
radx
The horizontal radius of each corner.
rady
The vertical radius of each corner.

Returns

Nothing.

Comments

The current point is moved to the top-left corner before the rectangle is added to the path. The rectangle is drawn clockwise from the top left corner, resulting in a current point that is the top left corner of the rectangle.

The corners are constructed using the same algorithm that GcArcTo() uses.

This function adds to the current path in the rendering state; it does not draw to the screen. To draw the current path to the screen, call GcPaint().

See Also

GcRect(), GcRectI()

GcScale Function ^TOP^

Purpose

Scales the coordinate system.

Declared In

GcRender.h

Prototype

void GcScale (
   GcHandle ctxt,
   fcoord_t sx,
   fcoord_t sy
)

Parameters

ctxt
The graphics context.
sx
Horizontal scaling factor. This must be a positive value.
sy
Vertical scaling factor. This must be a positive value.

Returns

Nothing.

Comments

A two-dimensional transformation affects only the drawing functions called after it. If you call this function in the middle of a path definition, it applies only to those points in the path defined after this function is called. If you are creating a stroked path, call this and all other two-dimensional transformations before calling GcStroke().

Scaling occurs starting from the origin of the screen. If you want to scale a path with respect to its center, use GcTranslate() to translate the origin to the path's center before scaling. See GcRotate() for sample code.

See Also

GcReflect(), GcShear(), GcTransform()

GcSetAntialiasing Function ^TOP^

Purpose

Specifies whether the rendering system uses antialiasing when drawing.

Declared In

GcRender.h

Prototype

void GcSetAntialiasing (
   GcHandle ctxt,
   uint32_t value
)

Parameters

ctxt
The graphics context.
value
One of the GcAliasingTag constants.

Returns

Nothing.

Comments

You rarely need to use this function. Do so only if you are creating a drawing application and want more control over the quality of the rendered image. The default value for antialiasing suffices in most cases.

If the system does not support antialiasing, this setting is ignored.

See Also

GcSetFontAntialiasing()

GcSetCaps Function ^TOP^

Purpose

Specifies what the line end points look like in a stroked path.

Declared In

GcRender.h

Prototype

void GcSetCaps (
   GcHandle ctxt,
   int32_t start_cap,
   int32_t end_cap
)

Parameters

ctxt
The graphics context.
start_cap
A GcCapTag value that specifies how the start of each subpath will look.
end_cap
A GcCapTag value that specifies how the end of each subpath will look.

Returns

Nothing.

Comments

This function only affects paths where GcStroke() is called before GcPaint().

GcSetColor Function ^TOP^

Purpose

Sets the color used with GcPaint().

Declared In

GcRender.h

Prototype

void GcSetColor (
   GcHandle ctxt,
   uint8_t r,
   uint8_t g,
   uint8_t b,
   uint8_t a
)

Parameters

ctxt
The graphics context.
r
The red value.
g
The green value.
b
The blue value.
a
The level of opacity where 255 is fully opaque.

Returns

Nothing.

Comments

Palm OS supports up to 16-bit direct color displays, which typically uses 5 bits for red, 6 bits for green, and 5 bits for blue. If you specify larger red, green, or blue values, the rendering system converts them before they are drawn to the screen.

See Also

GcSetGradient()

GcSetCoordinateSystem Function ^TOP^

Purpose

Sets the coordinate system used by subsequent drawing operations.

Declared In

GcRender.h

Prototype

void GcSetCoordinateSystem (
   GcHandle ctxt,
   uint32_t coordinateSystem
)

Parameters

ctxt
The graphics context.
coordinateSystem
One of the Coordinate System Constants. The default coordinate system for all graphics context drawing is the native screen format.

Returns

Nothing.

Comments

It is best to set the coordinate system before any drawing is done. Suppose the current coordinate system is native, and you do something like that shown below on a double-density device:


GcHandle ctxt = GcGetCurrentContext(); 
 
//Draw a line 
GcMoveTo(ctxt, 0, 10); 
GcDrawLine(ctxt, 0, 160); 
 
//Draw another line  
GcMoveTo(ctxt, 0, 20); 
GcDrawLine(ctxt, 0, 160); 
GcMoveTo(ctxt, 0, 40); 
 
//BAD Code! Applies only to the next line.  
GcSetCoordinateSystem(ctxt, kCoordinatesStandard); 
GcLineTo(ctxt, 0, 160); 
 
GcStroke(ctxt); 
GcPaint(ctxt); 
GcReleaseContext(ctxt); 

The last line will be twice as long as the other two because the coordinate system switched to standard before its bounds were computed.

The default coordinate system for the graphics context is the coordinate system used by the current draw window.

Be careful not to confuse WinSetCoordinateSystem() and this function. If you call GcSetCoordinateSystem(), it changes only the coordinate system used by the graphics context, not by the Window Manager. It is a good idea to always make both calls so that you can be certain both coordinate systems are the same.

GcSetFont Function ^TOP^

Purpose

Sets the font used by GcDrawTextAt().

Declared In

GcRender.h

Prototype

void GcSetFont (
   GcHandle ctxt,
   GcFontHandle font
)

Parameters

ctxt
The graphics context.
font
The scalable font to use.

Returns

Nothing.

See Also

GcCreateFont(), GcCreateFontFromFamily(), GcCreateFontFromID()

GcSetGradient Function ^TOP^

Purpose

Sets the gradient used with GcPaint().

Declared In

GcRender.h

Prototype

void GcSetGradient (
   GcHandle ctxt,
   const GcGradientType *gradient
)

Parameters

ctxt
The graphics context.
gradient
A GcGradientType structure defining the gradations to use.

Returns

Nothing.

Comments

Any two-dimensional transformations that are set before this call are applied to the gradient when drawing takes place. If you don't want the transformation applied to the gradient, call GcSetGradient() first, and then set the transformations.

See Also

GcSetColor(), GcInitGradient()

GcSetJoin Function ^TOP^

Purpose

Specifies what the intersection of two lines looks like in a stroked (outlined) path.

Declared In

GcRender.h

Prototype

void GcSetJoin (
   GcHandle ctxt,
   int32_t join,
   float miter_limit
)

Parameters

ctxt
The graphics context.
join
One of the GcJoinTag values.
miter_limit
Controls when the rendering system switches from a miter join to a bevel join. When the length of the point reaches miter_limit times the stroke weight, the rendering system switches from a miter join to a bevel join. This only applies to the miter join, not to any of the other join styles.

Returns

Nothing.

Comments

This function only has affect for paths where GcStroke() is called before GcPaint().

GcSetPenSize Function ^TOP^

Purpose

Sets the border width used to draw stroked paths.

Declared In

GcRender.h

Prototype

void GcSetPenSize (
   GcHandle ctxt,
   fcoord_t penWidth
)

Parameters

ctxt
The graphics context.
penWidth
The pen width given in coordinates.

Returns

Nothing.

Comments

This function only has affect for paths where GcStroke() is called before GcPaint().

When the path is drawn, rendering system ensures that the path is in the middle of the pen. A path is always assumed to have no width. For example, if you give a path that consists of one vertical line drawn from (1, 0) to (1, 160) and a pen width of 2, GcPaint() colors all pixels in the 0 column and all pixels in the 1 column.

GcShear Function ^TOP^

Purpose

Applies the shear transformation to the coordinate system.

Declared In

GcRender.h

Prototype

void GcShear (
   GcHandle ctxt,
   fcoord_t x,
   fcoord_t y
)

Parameters

ctxt
The graphics context.
x
The amount of shear in the horizontal direction.
y
The amount of shear in the vertical direction.

Returns

Nothing.

Comments

The shear transformation angles and stretches a shape. It is most commonly used to convert a font to italics or to convert a rectangle into a parallelogram.

A two-dimensional transformation affects only the drawing functions called after it. If you call this function in the middle of a path definition, it applies only to those points in the path defined after this function is called. If you are creating a stroked path, call this and all other two-dimensional transformations before calling GcStroke().

The shear transformation is applied starting from the origin of the screen. If you want to angle and stretch a shape but have it appear in the same general location on the screen, use GcTranslate() to translate the origin to the center of the screen before calling this function. See GcRotate() for sample code.

See Also

GcReflect(), GcScale(), GcTranslate(), GcTransform()

GcStroke Function ^TOP^

Purpose

Changes the current path to the outline of an object rather than a filled object.

Declared In

GcRender.h

Prototype

void GcStroke (
   GcHandle ctxt
)

Parameters

ctxt
The graphics context.

Returns

Nothing.

Comments

Use this function if you want GcPaint() to trace the outline of the path rather than filling the path.

The pen size, join, and cap style portions of the rendering state apply if you call this function. Pen size, join, and cap style do not affect fill operations.

The current two-dimensional transformation also affects the stroke. Do not change the two-dimensional transformation in between calls to this function and GcPaint().

See Also

GcReflect(), GcRotate(), GcScale(), GcSetCaps(), GcSetJoin(), GcSetPenSize(), GcTranslate()

GcTransform Function ^TOP^

Purpose

Applies a general two-dimensional transformation matrix.

Declared In

GcRender.h

Prototype

void GcTransform (
   GcHandle ctxt,
   const fcoord_t *matrix
)

Parameters

ctxt
The graphics context.
matrix
The transformation matrix to be applied.

Returns

Nothing.

Comments

This function applies a general two-dimensional transformation like that in the Postscript language. The transformation is described by the matrix shown in Figure 21.7.

Figure 21.7  Transformation matrix

The coordinates in this matrix are applied to each point in the current path according to the following equations:

newX = (matrix[0] * currentX) + (matrix[2] * 
currentY) + matrix[4]
newY = (matrix[1] * currentX) + (matrix[3] * 
currentY) + matrix[5]

where (currentX, currentY) represents a point on the path and (newX, newY) represents that point after the transformation has been applied.

See Also

GcTranslate(), GcScale(), GcRotate(), GcReflect(), GcSetFontTransform()

GcTranslate Function ^TOP^

Purpose

Translates the coordinate system by moving the origin to the specified coordinates.

Declared In

GcRender.h

Prototype

void GcTranslate (
   GcHandle ctxt,
   fcoord_t x,
   fcoord_t y
)

Parameters

ctxt
The graphics context.
x
The horizontal amount to move.
y
The vertical amount to move.

Returns

Nothing.

Comments

If you are creating a stroked path, call this and all other two-dimensional transformations before calling GcStroke(). Typically, you specify the transformation before you do any drawing.

This function is often used in conjunction with other transformations to ensure that the transformed path still appears on the screen. See GcRotate() for sample code.

See Also

GcReflect(), GcShear(), GcTransform()