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
GcBitmapHandle Struct
Purpose
The handle to an internal structure that represents the bitmap.
Declared In
GcRender.h
Prototype
typedef struct GcBitmapType *GcBitmapHandle
Fields
See Also
GcDrawBitmapAt()
, GcDrawRawBitmapAt()
, GcPaintBitmap()
, GcLoadBitmap()
, GcReleaseBitmap()
, FrmGetBitmapHandle()
GcBitmapType Struct
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
See Also
GcLoadBitmap()
, GcBitmapHandle
GcColorType Struct
Purpose
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
Purpose
Internal structure that keeps track of the current rendering state.
Declared In
GcRender.h
Prototype
struct GcContextType
Fields
See Also
GcHandle Typedef
Purpose
The handle of a graphics context.
Declared In
GcRender.h
Prototype
typedef struct GcContextType *GcHandle
Fields
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
GcGradientType Struct
Purpose
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
Bitmap Loading Enum
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()
withkBitmapScalingOff
.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
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.

GcJoinTag Enum
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()
orGcBezierTo()
). -
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.

See Also
Transform Indexes Enum
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
GcArc Function
Purpose
Adds an arc to the current path.
Declared In
GcRender.h
Prototype
void GcArc ( GcHandlectxt
, fcoord_tcenterX
, fcoord_tcenterY
, fcoord_tradx
, fcoord_trady
, floatstartAngle
, floatarcLen
, Booleanconnected
)
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. Iffalse
, the arc is drawn without connecting to the center point.
Returns
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.

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 Function
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 ( GcHandlectxt
, fcoord_tp1x
, fcoord_tp1y
, fcoord_tp2x
, fcoord_tp2y
, floatradius
)
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
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.

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
GcBeginClip Function
Purpose
Begins a block of code that specifies a clipping region.
Declared In
GcRender.h
Prototype
void GcBeginClip ( GcHandlectxt
, Booleaninverse
)
Parameters
-
→ ctxt
- The graphics context.
-
→
inverse
- If
true
, the region that you define will be the inverse of the clipping region. Iffalse
, the region you define will be the clipping region.
Returns
Comments
To specify a clipping region, do the following:
- Call
GcPushState()
. - Call
GcBeginClip()
. - Call one or more of the path definition functions to specify the clipping region.
- Call
GcPaint()
, which fills the specified region with white. - 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
Purpose
Add a Bezier curve to the path.
Declared In
GcRender.h
Prototype
void GcBezierTo ( GcHandlectxt
, fcoord_tp1x
, fcoord_tp1y
, fcoord_tp2x
, fcoord_tp2y
, fcoord_tp3x
, fcoord_tp3y
)
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
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.

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
GcClosePath Function
Purpose
Closes the current subpath using a straight line.
Declared In
GcRender.h
Prototype
void GcClosePath (
GcHandle ctxt
)
Parameters
Returns
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
Purpose
Blocks until all pending drawing operations are completed.
Declared In
GcRender.h
Prototype
void GcCommit (
GcHandle ctxt
)
Parameters
Returns
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
GcCreateBitmapContext Function
Purpose
Create a rendering context in a given bitmap.
Declared In
GcRender.h
Prototype
GcHandle GcCreateBitmapContext (
const BitmapType *bitmapP
)
Parameters
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
GcDrawBitmapAt Function
Purpose
Paints the bitmap at the specified coordinates.
Declared In
GcRender.h
Prototype
void GcDrawBitmapAt ( GcHandlectxt
, GcBitmapHandlebitmapHandle
, const FAbsRectType*srcRect
, fcoord_tx
, fcoord_ty
)
Parameters
-
→ ctxt
- The graphics context.
-
→ bitmapHandle
- The bitmap. Use
FrmGetBitmapHandle()
orGcLoadBitmap()
to obtain aGcBitmapHandle
to a bitmap. -
→ srcRect
- Rectangle (see
FAbsRectType
) that specifies the portion of the bitmap to be drawn to the screen. PassNULL
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
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 Function
Purpose
Paints a bitmap at the specified coordinates.
Declared In
GcRender.h
Prototype
void GcDrawRawBitmapAt ( GcHandlectxt
, const BitmapType*bitmapP
, const FAbsRectType*srcRect
, fcoord_tx
, fcoord_ty
, uint32_tload_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. PassNULL
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
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
Purpose
Draws text to the screen using the font specified by GcSetFont()
.
Declared In
GcRender.h
Prototype
void GcDrawTextAt ( GcHandlectxt
, fcoord_tx
, fcoord_ty
, const char *text
, int32_tlength
)
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 iftext
is a null-terminated string.
Returns
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
GcEndClip Function
Purpose
Ends the specification of a clipping region.
Declared In
GcRender.h
Prototype
void GcEndClip (
GcHandle ctxt
)
Parameters
Returns
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
Purpose
Blocks until all pending drawing operations have been sent.
Declared In
GcRender.h
Prototype
void GcFlush (
GcHandle ctxt
)
Parameters
Returns
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
Purpose
Returns the density of a bitmap.
Declared In
GcRender.h
Prototype
uint16_t GcGetBitmapDensity (
GcBitmapHandle bitmapHandle
)
Parameters
-
→ bitmapHandle
- The bitmap. Use
FrmGetBitmapHandle()
orGcLoadBitmap()
to obtain aGcBitmapHandle
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
Purpose
Retrieves the depth of a bitmap.
Declared In
GcRender.h
Prototype
uint32_t GcGetBitmapDepth (
GcBitmapHandle bitmapHandle
)
Parameters
-
→
bitmapHandle
- The bitmap. Use
FrmGetBitmapHandle()
orGcLoadBitmap()
to obtain aGcBitmapHandle
to a bitmap.
Returns
GcGetBitmapHeight Function
Purpose
Returns the height of a bitmap.
Declared In
GcRender.h
Prototype
uint32_t GcGetBitmapHeight (
GcBitmapHandle bitmapHandle
)
Parameters
-
→
bitmapHandle
- The bitmap. Use
FrmGetBitmapHandle()
orGcLoadBitmap()
to obtain aGcBitmapHandle
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
Purpose
Returns the width of the bitmap.
Declared In
GcRender.h
Prototype
uint32_t GcGetBitmapWidth (
GcBitmapHandle bitmapHandle
)
Parameters
-
→
bitmapHandle
- The bitmap. Use
FrmGetBitmapHandle()
orGcLoadBitmap()
to obtain aGcBitmapHandle
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
Purpose
Creates the graphics context for the current draw window.
Declared In
GcRender.h
Prototype
GcHandle GcGetCurrentContext ( void )
Parameters
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
GcInitGradient Function
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_tnum
)
Parameters
-
← gradient
- Contains the gradient upon return. See
GcGradientType
. -
→ points
- An array of points (see
GcPointType
). The number of points is specified innum
. -
→ colors
- An array of colors (see
GcColorType
). The number of colors is specified innum
. -
→ 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
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()
orGcLoadBitmap()
to obtain aGcBitmapHandle
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
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 ( GcHandlectxt
, fcoord_tx
, fcoord_t y )
Parameters
-
→ ctxt
- The graphics context.
-
→ x, y
- Ending point of the line to draw. This point becomes the current point.
Returns
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
GcLoadBitmap Function
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 ( WinHandlewin
, const void*bitmapFileP
, size_tsize
, uint32_tflags
)
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
Purpose
Moves the current point to the coordinates specified.
Declared In
GcRender.h
Prototype
void GcMoveTo ( GcHandlectxt
, fcoord_tx
, fcoord_ty
)
Parameters
Returns
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
Purpose
Paints the current path onto the screen.
Declared In
GcRender.h
Prototype
void GcPaint (
GcHandle ctxt
)
Parameters
Returns
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
Purpose
Fills the current path with the specified bitmap.
Declared In
GcRender.h
Prototype
void GcPaintBitmap ( GcHandlectxt
, GcBitmapHandlebitmapHandle
)
Parameters
-
→ ctxt
- The graphics context.
-
→ bitmapHandle
- The bitmap to draw to the screen. Use
GcLoadBitmap()
to obtain aGcBitmapHandle
to a bitmap.
Returns
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
Purpose
Restores the previous rendering state.
Declared In
GcRender.h
Prototype
void GcPopState (
GcHandle ctxt
)
Parameters
Returns
See Also
GcPushState Function
Purpose
Saves the current rendering state.
Declared In
GcRender.h
Prototype
void GcPushState (
GcHandle ctxt
)
Parameters
Returns
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
GcRect Function
Purpose
Declared In
GcRender.h
Prototype
void GcRect ( GcHandlectxt
, fcoord_tleft
, fcoord_ttop
, fcoord_tright
, fcoord_tbottom
)
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
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
GcRectI Function
Purpose
Adds a rectangle to the path using integer coordinates to define the rectangle.
Declared In
GcRender.h
Prototype
void GcRectI ( GcHandlectxt
, int32_tleft
, int32_ttop
, int32_tright
, int32_tbottom
)
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
Comments
This function differs from GcRect()
in that it takes integer coordinates rather than floating-point coordinates.
GcReflect Function
Purpose
Flips the coordinate system at the specified radius.
Declared In
GcRender.h
Prototype
void GcReflect ( GcHandlectxt
, fcoord_trad
)
Parameters
Returns
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
GcReleaseBitmap Function
Purpose
Releases the memory associated with the bitmap handle.
Declared In
GcRender.h
Prototype
status_t GcReleaseBitmap (
GcBitmapHandle bitmapHandle
)
Parameters
Returns
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
GcReleaseContext Function
Purpose
Declared In
GcRender.h
Prototype
void GcReleaseContext (
GcHandle ctxt
)
Parameters
Returns
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
Purpose
Rotates the coordinate system the number of radians.
Declared In
GcRender.h
Prototype
void GcRotate ( GcHandlectxt
, fcoord_trad
)
Parameters
Returns
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
Purpose
Creates a rectangle path with rounded corners.
Declared In
GcRender.h
Prototype
void GcRoundRect ( GcHandlectxt
, fcoord_tleft
, fcoord_ttop
, fcoord_tright
, fcoord_tbottom
, fcoord_tradx
, fcoord_trady
)
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
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
GcScale Function
Purpose
Declared In
GcRender.h
Prototype
void GcScale ( GcHandlectxt
, fcoord_tsx
, fcoord_tsy
)
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
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
Purpose
Specifies whether the rendering system uses antialiasing when drawing.
Declared In
GcRender.h
Prototype
void GcSetAntialiasing ( GcHandlectxt
, uint32_tvalue
)
Parameters
-
→ ctxt
- The graphics context.
-
→ value
- One of the
GcAliasingTag
constants.
Returns
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
GcSetCaps Function
Purpose
Specifies what the line end points look like in a stroked path.
Declared In
GcRender.h
Prototype
void GcSetCaps ( GcHandlectxt
, int32_tstart_cap
, int32_tend_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
Comments
This function only affects paths where GcStroke()
is called before GcPaint()
.
GcSetColor Function
Purpose
Sets the color used with GcPaint()
.
Declared In
GcRender.h
Prototype
void GcSetColor ( GcHandlectxt
, uint8_tr
, uint8_tg
, uint8_tb
, uint8_ta
)
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
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
GcSetCoordinateSystem Function
Purpose
Sets the coordinate system used by subsequent drawing operations.
Declared In
GcRender.h
Prototype
void GcSetCoordinateSystem ( GcHandlectxt
, uint32_tcoordinateSystem
)
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
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
Purpose
Sets the font used by GcDrawTextAt()
.
Declared In
GcRender.h
Prototype
void GcSetFont ( GcHandlectxt
, GcFontHandlefont
)
Parameters
Returns
See Also
GcCreateFont()
, GcCreateFontFromFamily()
, GcCreateFontFromID()
GcSetGradient Function
Purpose
Sets the gradient used with GcPaint()
.
Declared In
GcRender.h
Prototype
void GcSetGradient ( GcHandlectxt
, const GcGradientType *gradient
)
Parameters
-
→ ctxt
- The graphics context.
-
→ gradient
- A
GcGradientType
structure defining the gradations to use.
Returns
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
Purpose
Specifies what the intersection of two lines looks like in a stroked (outlined) path.
Declared In
GcRender.h
Prototype
void GcSetJoin ( GcHandlectxt
, int32_tjoin
, floatmiter_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
Comments
This function only has affect for paths where GcStroke()
is called before GcPaint()
.
GcSetPenSize Function
Purpose
Sets the border width used to draw stroked paths.
Declared In
GcRender.h
Prototype
void GcSetPenSize ( GcHandlectxt
, fcoord_tpenWidth
)
Parameters
Returns
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
Purpose
Applies the shear transformation to the coordinate system.
Declared In
GcRender.h
Prototype
void GcShear ( GcHandlectxt
, fcoord_tx
, fcoord_ty
)
Parameters
-
→ ctxt
- The graphics context.
-
→ x
- The amount of shear in the horizontal direction.
-
→ y
- The amount of shear in the vertical direction.
Returns
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
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
Returns
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
Purpose
Applies a general two-dimensional transformation matrix.
Declared In
GcRender.h
Prototype
void GcTransform ( GcHandlectxt
, const fcoord_t*matrix
)
Parameters
Returns
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
Purpose
Translates the coordinate system by moving the origin to the specified coordinates.
Declared In
GcRender.h
Prototype
void GcTranslate ( GcHandlectxt
, fcoord_tx
, fcoord_ty
)
Parameters
Returns
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()