Functions to draw into a graphics context. More...

Collaboration diagram for Drawing Primitives:

Enumerations
enum	GCornerMask { GCornerNone = 0, GCornerTopLeft = 1 << 0, GCornerTopRight = 1 << 1, GCornerBottomLeft = 1 << 2, GCornerBottomRight = 1 << 3, GCornersAll = GCornerTopLeft \| GCornerTopRight \| GCornerBottomLeft \| GCornerBottomRight, GCornersTop = GCornerTopLeft \| GCornerTopRight, GCornersBottom = GCornerBottomLeft \| GCornerBottomRight, GCornersLeft = GCornerTopLeft \| GCornerBottomLeft, GCornersRight = GCornerTopRight \| GCornerBottomRight }

enum	GOvalScaleMode { GOvalScaleModeFitCircle, GOvalScaleModeFillCircle }

Functions
void	graphics_draw_pixel (GContext *ctx, GPoint point)

void	graphics_draw_line (GContext *ctx, GPoint p0, GPoint p1)

void	graphics_draw_rect (GContext *ctx, GRect rect)

void	graphics_fill_rect (GContext *ctx, GRect rect, uint16_t corner_radius, GCornerMask corner_mask)

void	graphics_draw_circle (GContext *ctx, GPoint p, uint16_t radius)

void	graphics_fill_circle (GContext *ctx, GPoint p, uint16_t radius)

void	graphics_draw_round_rect (GContext *ctx, GRect rect, uint16_t radius)

void	graphics_draw_bitmap_in_rect (GContext ctx, const GBitmap bitmap, GRect rect)

GBitmap *	graphics_capture_frame_buffer (GContext *ctx)

GBitmap *	graphics_capture_frame_buffer_format (GContext *ctx, GBitmapFormat format)

bool	graphics_release_frame_buffer (GContext ctx, GBitmap buffer)

bool	graphics_frame_buffer_is_captured (GContext *ctx)

void	graphics_draw_rotated_bitmap (GContext ctx, GBitmap src, GPoint src_ic, int rotation, GPoint dest_ic)

void	graphics_draw_arc (GContext *ctx, GRect rect, GOvalScaleMode scale_mode, int32_t angle_start, int32_t angle_end)

void	graphics_fill_radial (GContext *ctx, GRect rect, GOvalScaleMode scale_mode, uint16_t inset_thickness, int32_t angle_start, int32_t angle_end)

GPoint	gpoint_from_polar (GRect rect, GOvalScaleMode scale_mode, int32_t angle)

GRect	grect_centered_from_polar (GRect rect, GOvalScaleMode scale_mode, int32_t angle, GSize size)

Detailed Description

Functions to draw into a graphics context.

Use these drawing functions inside a Layer's .update_proc drawing callback. A GContext is passed into this callback as an argument. This GContext can then be used with all of the drawing functions which are documented below. See Graphics Context for more information about the graphics context.

Refer to (chapter "Layers" and "Graphics") for a conceptual overview of the drawing system, Layers and relevant code examples.

Other drawing functions and related documentation:

Enumeration Type Documentation

◆ GCornerMask

enum GCornerMask

Bit mask values to specify the corners of a rectangle. The values can be combines using binary OR (|), For example: the mask to indicate top left and bottom right corners can: be created as follows: (GCornerTopLeft | GCornerBottomRight)

Enumerator
GCornerNone	No corners.
GCornerTopLeft	Top-Left corner.
GCornerTopRight	Top-Right corner.
GCornerBottomLeft	Bottom-Left corner.
GCornerBottomRight	Bottom-Right corner.
GCornersAll	All corners.
GCornersTop	Top corners.
GCornersBottom	Bottom corners.
GCornersLeft	Left corners.
GCornersRight	Right corners.

◆ GOvalScaleMode

enum GOvalScaleMode

Values to specify how a given rectangle should be used to derive an oval shape.

See also: graphics_fill_radial_internal; graphics_draw_arc_internal; gpoint_from_polar_internal; grect_centered_from_polar

Enumerator
GOvalScaleModeFitCircle	Places the largest possible fully visible circle in the center of a rectangle.
GOvalScaleModeFillCircle	Places the smallest possible circle in the center of a rectangle so that the rectangle is fully inside the circle.

Function Documentation

◆ gpoint_from_polar()

GPoint gpoint_from_polar	(	GRect	rect,
		GOvalScaleMode	scale_mode,
		int32_t	angle
	)

Calculates a GPoint located at the angle provided on the perimeter of a circle defined by the provided GRect.

Parameters

rect	The reference rectangle to derive the center point and radius (see scale_mode).
scale_mode	Determines how rect will be used to derive the center point and radius.
angle	The angle at which the point on the circle's perimeter should be calculated. Use DEG_TO_TRIGANGLE to easily convert degrees to the appropriate value.

Returns: The point on the circle's perimeter.

◆ graphics_capture_frame_buffer()

GBitmap* graphics_capture_frame_buffer ( GContext * ctx )

A shortcut to capture the framebuffer in the native format of the watch.

See also: graphics_capture_frame_buffer_format

◆ graphics_capture_frame_buffer_format()

GBitmap* graphics_capture_frame_buffer_format	(	GContext *	ctx,
		GBitmapFormat	format
	)

Captures the frame buffer for direct access, using the given format. Graphics functions will not affect the frame buffer while it is captured. The frame buffer is released when graphics_release_frame_buffer is called. The frame buffer must be released before the end of a layer's .update_proc for the layer to be drawn properly.

While the frame buffer is captured calling graphics_capture_frame_buffer will fail and return NULL.

Note: When writing to the frame buffer, you should respect the visible boundaries of a window on the screen. Use layer_get_frame(window_get_root_layer(window)).origin to obtain its position relative to the frame buffer. For example, drawing to (5, 5) in the frame buffer while the window is transitioning to the left with its origin at (-20, 0) would effectively draw that point at (25, 5) relative to the window. For this reason you should consider the window's root layer frame when calculating drawing coordinates.

See also: GBitmap; GBitmapFormat; layer_get_frame; window_get_root_layer

Parameters

ctx	The graphics context providing the frame buffer
format	The format in which the framebuffer should be captured. Supported formats are GBitmapFormat1Bit and GBitmapFormat8Bit.

Returns: A pointer to the frame buffer. NULL if failed.

◆ graphics_draw_arc()

void graphics_draw_arc	(	GContext *	ctx,
		GRect	rect,
		GOvalScaleMode	scale_mode,
		int32_t	angle_start,
		int32_t	angle_end
	)

Draws a line arc clockwise between angle_start and angle_end, where 0° is the top of the circle. If the difference between angle_start and angle_end is greater than 360°, a full circle will be drawn.

Parameters

ctx	The destination graphics context in which to draw using the current stroke color and antialiasing setting.
rect	The reference rectangle to derive the center point and radius (see scale_mode).
scale_mode	Determines how rect will be used to derive the center point and radius.
angle_start	Radial starting angle. Use DEG_TO_TRIGANGLE to easily convert degrees to the appropriate value.
angle_end	Radial finishing angle. If smaller than `angle_start`, nothing will be drawn.

◆ graphics_draw_bitmap_in_rect()

void graphics_draw_bitmap_in_rect	(	GContext *	ctx,
		const GBitmap *	bitmap,
		GRect	rect
	)

Draws a bitmap into the graphics context, inside the specified rectangle

Parameters

ctx	The destination graphics context in which to draw the bitmap
bitmap	The bitmap to draw
rect	The rectangle in which to draw the bitmap

Note: If the size of rect is smaller than the size of the bitmap, the bitmap will be clipped on right and bottom edges. If the size of rect is larger than the size of the bitmap, the bitmap will be tiled automatically in both horizontal and vertical directions, effectively drawing a repeating pattern.

See also: GBitmap; GContext

◆ graphics_draw_circle()

void graphics_draw_circle	(	GContext *	ctx,
		GPoint	p,
		uint16_t	radius
	)

Draws the outline of a circle in the current stroke color

Parameters

ctx	The destination graphics context in which to draw
p	The center point of the circle
radius	The radius in pixels

◆ graphics_draw_line()

void graphics_draw_line	(	GContext *	ctx,
		GPoint	p0,
		GPoint	p1
	)

Draws line in the current stroke color, current stroke width and AA flag

Parameters

ctx	The destination graphics context in which to draw
p0	The starting point of the line
p1	The ending point of the line

◆ graphics_draw_pixel()

void graphics_draw_pixel	(	GContext *	ctx,
		GPoint	point
	)

Draws a pixel at given point in the current stroke color

Parameters

ctx	The destination graphics context in which to draw
point	The point at which to draw the pixel

◆ graphics_draw_rect()

void graphics_draw_rect	(	GContext *	ctx,
		GRect	rect
	)

Draws a 1-pixel wide rectangle outline in the current stroke color

Parameters

ctx	The destination graphics context in which to draw
rect	The rectangle for which to draw the outline

◆ graphics_draw_rotated_bitmap()

void graphics_draw_rotated_bitmap	(	GContext *	ctx,
		GBitmap *	src,
		GPoint	src_ic,
		int	rotation,
		GPoint	dest_ic
	)

Draws a rotated bitmap with a memory-sensitive 2x anti-aliasing technique (using ray-finding instead of super-sampling), which is thresholded into a b/w bitmap for 1-bit and color blended for 8-bit.

Note: This API has performance limitations that can degrade user experience. Use sparingly.

Parameters

ctx	The destination graphics context in which to draw
src	The source bitmap to draw
src_ic	Instance center (single point unaffected by rotation) relative to source bitmap
rotation	Angle of rotation. Rotation is an integer between 0 (no rotation) and TRIG_MAX_ANGLE (360 degree rotation). Use DEG_TO_TRIGANGLE to easily convert degrees to the appropriate value.
dest_ic	Where to draw the instance center of the rotated bitmap in the context.

◆ graphics_draw_round_rect()

void graphics_draw_round_rect	(	GContext *	ctx,
		GRect	rect,
		uint16_t	radius
	)

Draws the outline of a rounded rectangle in the current stroke color

Parameters

ctx	The destination graphics context in which to draw
rect	The rectangle defining the dimensions of the rounded rectangle to draw
radius	The corner radius in pixels

◆ graphics_fill_circle()

void graphics_fill_circle	(	GContext *	ctx,
		GPoint	p,
		uint16_t	radius
	)

Fills a circle in the current fill color

Parameters

ctx	The destination graphics context in which to draw
p	The center point of the circle
radius	The radius in pixels

◆ graphics_fill_radial()

void graphics_fill_radial	(	GContext *	ctx,
		GRect	rect,
		GOvalScaleMode	scale_mode,
		uint16_t	inset_thickness,
		int32_t	angle_start,
		int32_t	angle_end
	)

Fills a circle clockwise between angle_start and angle_end, where 0° is the top of the circle. If the difference between angle_start and angle_end is greater than 360°, a full circle will be drawn and filled. If angle_start is greater than angle_end nothing will be drawn.

Note: A simple example is drawing a 'Pacman' shape, with a starting angle of -225°, and ending angle of 45°. By setting inset_thickness to a non-zero value (such as 30) this example will produce the letter C.

Parameters

ctx	The destination graphics context in which to draw using the current fill color and antialiasing setting.
rect	The reference rectangle to derive the center point and radius (see scale).
scale_mode	Determines how rect will be used to derive the center point and radius.
inset_thickness	Describes how thick in pixels the radial will be drawn towards its center measured from the outside.
angle_start	Radial starting angle. Use DEG_TO_TRIGANGLE to easily convert degrees to the appropriate value.
angle_end	Radial finishing angle. If smaller than `angle_start`, nothing will be drawn.

◆ graphics_fill_rect()

void graphics_fill_rect	(	GContext *	ctx,
		GRect	rect,
		uint16_t	corner_radius,
		GCornerMask	corner_mask
	)

Fills a rectangle with the current fill color, optionally rounding all or a selection of its corners.

Parameters

ctx	The destination graphics context in which to draw
rect	The rectangle to fill
corner_radius	The rounding radius of the corners in pixels (maximum is 8 pixels)
corner_mask	Bitmask of the corners that need to be rounded.

See also: GCornerMask

◆ graphics_frame_buffer_is_captured()

bool graphics_frame_buffer_is_captured ( GContext * ctx )

Whether or not the frame buffer has been captured by graphics_capture_frame_buffer. Graphics functions will not affect the frame buffer until it has been released by graphics_release_frame_buffer.

Parameters

ctx	The graphics context providing the frame buffer

Returns: True if the frame buffer has been captured

◆ graphics_release_frame_buffer()

bool graphics_release_frame_buffer	(	GContext *	ctx,
		GBitmap *	buffer
	)

Releases the frame buffer. Must be called before the end of a layer's .update_proc for the layer to be drawn properly.

If buffer does not point to the address previously returned by graphics_capture_frame_buffer the frame buffer will not be released.

Parameters

ctx	The graphics context providing the frame buffer
buffer	The pointer to frame buffer

Returns: True if the frame buffer was released successfully

◆ grect_centered_from_polar()

GRect grect_centered_from_polar	(	GRect	rect,
		GOvalScaleMode	scale_mode,
		int32_t	angle,
		GSize	size
	)

Calculates a rectangle centered on the perimeter of a circle at a given angle. Use this to construct rectangles that follow the perimeter of a circle as an input for graphics_fill_radial_internal or graphics_draw_arc_internal, e.g. to draw circles every 30 degrees on a watchface.

Parameters

rect	The reference rectangle to derive the circle's center point and radius (see scale_mode).
scale_mode	Determines how rect will be used to derive the circle's center point and radius.
angle	The angle at which the point on the circle's perimeter should be calculated. Use DEG_TO_TRIGANGLE to easily convert degrees to the appropriate value.
size	Width and height of the desired rectangle.

Returns: The rectangle centered on the circle's perimeter.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ GCornerMask

◆ GOvalScaleMode

Function Documentation

◆ gpoint_from_polar()

◆ graphics_capture_frame_buffer()

◆ graphics_capture_frame_buffer_format()

◆ graphics_draw_arc()

◆ graphics_draw_bitmap_in_rect()

◆ graphics_draw_circle()

◆ graphics_draw_line()

◆ graphics_draw_pixel()

◆ graphics_draw_rect()

◆ graphics_draw_rotated_bitmap()

◆ graphics_draw_round_rect()

◆ graphics_fill_circle()

◆ graphics_fill_radial()

◆ graphics_fill_rect()

◆ graphics_frame_buffer_is_captured()

◆ graphics_release_frame_buffer()

◆ grect_centered_from_polar()