pebble
  • Tutorials
  • Get the SDK
  • Guides
  • Documentation
  • Examples
  • Community
  • Blog
  • More
Privacy
Cookies
Publish

Pebble C API

  • Pebble C API
  • Pebble JavaScript API
  • PebbleKit JS
  • PebbleKit iOS
  • PebbleKit Android
  • Foundation
    • App
    • App Communication
    • App Glance
    • AppMessage
    • AppSync
    • AppWorker
    • DataLogging
    • DataStructures
      • UUID
    • Dictation
    • Dictionary
    • Event Service
      • AccelerometerService
      • AppFocusService
      • BatteryStateService
      • CompassService
      • ConnectionService
      • HealthService
      • TickTimerService
    • Exit Reason
    • Internationalization
    • Launch Reason
    • Logging
    • Math
    • Memory Management
    • Platform
    • Resources
      • File Formats
    • Storage
    • Timer
    • Wakeup
    • Wall Time
    • WatchInfo
    • Rocky
  • Graphics
    • Draw Commands
    • Drawing Paths
    • Drawing Primitives
    • Drawing Text
    • Fonts
    • Graphics Context
    • Graphics Types
      • Color Definitions
  • User Interface
    • Animation
      • PropertyAnimation
    • Clicks
    • Layers
      • ActionBarLayer
      • BitmapLayer
      • MenuLayer
      • RotBitmapLayer
      • ScrollLayer
      • SimpleMenuLayer
      • StatusBarLayer
      • TextLayer
    • Light
    • Preferences
    • UnobstructedArea
    • Vibes
    • Window
      • ActionMenu
      • NumberWindow
    • Window Stack
  • Standard C
    • Format
    • Locale
    • Math
    • Memory
    • String
    • Time

Draw Commands

Pebble Draw Commands are a way to encode arbitrary path draw and fill calls in binary format, so that vector-like graphics can be represented on the watch.

These draw commands can be loaded from resources, manipulated in place and drawn to the current graphics context. Each GDrawCommand can be an arbitrary path or a circle with optional fill or stroke. The stroke width and color of the stroke and fill are also encoded within the GDrawCommand. Paths can can be drawn open or closed.

All aspects of a draw command can be modified, except for the number of points in a path (a circle only has one point, the center).

Draw commands are grouped into a GDrawCommandList, which can be drawn all at once. Each individual GDrawCommand can be accessed from a GDrawCommandList for modification.

A GDrawCommandList forms the basis for GDrawCommandImage and GDrawCommandFrame objects. A GDrawCommandImage represents a static image and can be represented by the PDC file format and can be loaded as a resource.

Once you have a GDrawCommandImage loaded in memory you can draw it on the screen in a LayerUpdateProc with the gdraw_command_image_draw().

A GDrawCommandFrame represents a single frame of an animated sequence, with multiple frames making up a single GDrawCommandSequence, which can also be stored as a PDC and loaded as a resource.

To draw a GDrawCommandSequence, use the gdraw_command_sequence_get_frame_by_elapsed() to obtain the current GDrawCommandFrame and gdraw_command_frame_draw() to draw it.

Draw commands also allow access to drawing with sub-pixel precision. The points are treated as Fixed point types in the format 13.3, so that 1/8th of a pixel precision is possible. Only the points in draw commands of the type GDrawCommandTypePrecisePath will be treated as higher precision.

Function Documentation

void gdraw_command_draw(GContext * ctx, GDrawCommand * command)

Draw a command.

Parameters

ctx

The destination graphics context in which to draw

command

GDrawCommand to draw

GDrawCommandType gdraw_command_get_type(GDrawCommand * command)

Get the command type.

Parameters

command

GDrawCommand from which to get the type

Returns

The type of the given GDrawCommand

void gdraw_command_set_fill_color(GDrawCommand * command, GColor fill_color)

Set the fill color of a command.

Parameters

command

ref DrawCommand for which to set the fill color

fill_color

GColor to set for the fill

GColor gdraw_command_get_fill_color(GDrawCommand * command)

Get the fill color of a command.

Parameters

command

GDrawCommand from which to get the fill color

Returns

fill color of the given GDrawCommand

void gdraw_command_set_stroke_color(GDrawCommand * command, GColor stroke_color)

Set the stroke color of a command.

Parameters

command

GDrawCommand for which to set the stroke color

stroke_color

GColor to set for the stroke

GColor gdraw_command_get_stroke_color(GDrawCommand * command)

Get the stroke color of a command.

Parameters

command

GDrawCommand from which to get the stroke color

Returns

The stroke color of the given GDrawCommand

void gdraw_command_set_stroke_width(GDrawCommand * command, uint8_t stroke_width)

Set the stroke width of a command.

Parameters

command

GDrawCommand for which to set the stroke width

stroke_width

stroke width to set for the command

uint8_t gdraw_command_get_stroke_width(GDrawCommand * command)

Get the stroke width of a command.

Parameters

command

GDrawCommand from which to get the stroke width

Returns

The stroke width of the given GDrawCommand

uint16_t gdraw_command_get_num_points(GDrawCommand * command)

Get the number of points in a command.

void gdraw_command_set_point(GDrawCommand * command, uint16_t point_idx, GPoint point)

Set the value of the point in a command at the specified index.

Parameters

command

GDrawCommand for which to set the value of a point

point_idx

Index of the point to set the value for

point

new point value to set

GPoint gdraw_command_get_point(GDrawCommand * command, uint16_t point_idx)

Get the value of a point in a command from the specified index.

Note

The index must be less than the number of points

Parameters

command

GDrawCommand from which to get a point

point_idx

The index to get the point for

Returns

The point in the GDrawCommand specified by point_idx

void gdraw_command_set_radius(GDrawCommand * command, uint16_t radius)

Set the radius of a circle command.

Note

This only works for commands of type GDrawCommandCircle

Parameters

command

GDrawCommand from which to set the circle radius

radius

The radius to set for the circle.

uint16_t gdraw_command_get_radius(GDrawCommand * command)

Get the radius of a circle command.

Note

this only works for commands of typeGDrawCommandCircle.

Parameters

command

GDrawCommand from which to get the circle radius

Returns

The radius in pixels if command is of type GDrawCommandCircle

void gdraw_command_set_path_open(GDrawCommand * command, bool path_open)

Set the path of a stroke command to be open.

Note

This only works for commands of type GDrawCommandPath and GDrawCommandPrecisePath

Parameters

command

GDrawCommand for which to set the path open status

path_open

true if path should be hidden

bool gdraw_command_get_path_open(GDrawCommand * command)

Return whether a stroke command path is open.

Note

This only works for commands of type GDrawCommandPath and GDrawCommandPrecisePath

Parameters

command

GDrawCommand from which to get the path open status

Returns

true if the path is open

void gdraw_command_set_hidden(GDrawCommand * command, bool hidden)

Set a command as hidden. This command will not be drawn when gdraw_command_draw is called with this command.

Parameters

command

GDrawCommand for which to set the hidden status

hidden

true if command should be hidden

bool gdraw_command_get_hidden(GDrawCommand * command)

Return whether a command is hidden.

Parameters

command

GDrawCommand from which to get the hidden status

Returns

true if command is hidden

void gdraw_command_frame_draw(GContext * ctx, GDrawCommandSequence * sequence, GDrawCommandFrame * frame, GPoint offset)

Draw a frame.

Parameters

ctx

The destination graphics context in which to draw

sequence

The sequence from which the frame comes from (this is required)

frame

Frame to draw

offset

Offset from draw context origin to draw the frame

void gdraw_command_frame_set_duration(GDrawCommandFrame * frame, uint32_t duration)

Set the duration of the frame.

Parameters

frame

GDrawCommandFrame for which to set the duration

duration

duration of the frame in milliseconds

uint32_t gdraw_command_frame_get_duration(GDrawCommandFrame * frame)

Get the duration of the frame.

Parameters

frame

GDrawCommandFrame from which to get the duration

Returns

duration of the frame in milliseconds

GDrawCommandImage * gdraw_command_image_create_with_resource(uint32_t resource_id)

Creates a GDrawCommandImage from the specified resource (PDC file)

Parameters

resource_id

Resource containing data to load and create GDrawCommandImage from.

Returns

GDrawCommandImage pointer if the resource was loaded, NULL otherwise

GDrawCommandImage * gdraw_command_image_clone(GDrawCommandImage * image)

Creates a GDrawCommandImage as a copy from a given image.

Parameters

image

Image to copy.

Returns

cloned image or NULL if the operation failed

void gdraw_command_image_destroy(GDrawCommandImage * image)

Deletes the GDrawCommandImage structure and frees associated data.

Parameters

image

Pointer to the image to free (delete)

void gdraw_command_image_draw(GContext * ctx, GDrawCommandImage * image, GPoint offset)

Draw an image.

Parameters

ctx

The destination graphics context in which to draw

image

Image to draw

offset

Offset from draw context origin to draw the image

GSize gdraw_command_image_get_bounds_size(GDrawCommandImage * image)

Get size of the bounding box surrounding all draw commands in the image. This bounding box can be used to set the graphics context or layer bounds when drawing the image.

Parameters

image

GDrawCommandImage from which to get the bounding box size

Returns

bounding box size

void gdraw_command_image_set_bounds_size(GDrawCommandImage * image, GSize size)

Set size of the bounding box surrounding all draw commands in the image. This bounding box can be used to set the graphics context or layer bounds when drawing the image.

Parameters

image

GDrawCommandImage for which to set the bounding box size

size

bounding box size

GDrawCommandList * gdraw_command_image_get_command_list(GDrawCommandImage * image)

Get the command list of the image.

Parameters

image

GDrawCommandImage from which to get the command list

Returns

command list

void gdraw_command_list_iterate(GDrawCommandList * command_list, GDrawCommandListIteratorCb handle_command, void * callback_context)

Iterate over all commands in a command list.

Parameters

command_list

GDrawCommandList over which to iterate

handle_command

iterator callback

callback_context

context pointer to be passed into the iterator callback

void gdraw_command_list_draw(GContext * ctx, GDrawCommandList * command_list)

Draw all commands in a command list.

Parameters

ctx

The destination graphics context in which to draw

command_list

list of commands to draw

GDrawCommand * gdraw_command_list_get_command(GDrawCommandList * command_list, uint16_t command_idx)

Get the command at the specified index.

Note

the specified index must be less than the number of commands in the list

Parameters

command_list

GDrawCommandList from which to get a command

command_idx

index of the command to get

Returns

pointer to GDrawCommand at the specified index

uint32_t gdraw_command_list_get_num_commands(GDrawCommandList * command_list)

Get the number of commands in the list.

Parameters

command_list

GDrawCommandList from which to get the number of commands

Returns

number of commands in command list

GDrawCommandSequence * gdraw_command_sequence_create_with_resource(uint32_t resource_id)

Creates a GDrawCommandSequence from the specified resource (PDC file)

Parameters

resource_id

Resource containing data to load and create GDrawCommandSequence from.

Returns

GDrawCommandSequence pointer if the resource was loaded, NULL otherwise

GDrawCommandSequence * gdraw_command_sequence_clone(GDrawCommandSequence * sequence)

Creates a GDrawCommandSequence as a copy from a given sequence.

Parameters

sequence

Sequence to copy

Returns

cloned sequence or NULL if the operation failed

void gdraw_command_sequence_destroy(GDrawCommandSequence * sequence)

Deletes the GDrawCommandSequence structure and frees associated data.

Parameters

image

Pointer to the sequence to destroy

GDrawCommandFrame * gdraw_command_sequence_get_frame_by_elapsed(GDrawCommandSequence * sequence, uint32_t elapsed_ms)

Get the frame that should be shown after the specified amount of elapsed time The last frame will be returned if the elapsed time exceeds the total time.

Parameters

sequence

GDrawCommandSequence from which to get the frame

elapsed_ms

elapsed time in milliseconds

Returns

pointer to GDrawCommandFrame that should be displayed at the elapsed time

GDrawCommandFrame * gdraw_command_sequence_get_frame_by_index(GDrawCommandSequence * sequence, uint32_t index)

Get the frame at the specified index.

Parameters

sequence

GDrawCommandSequence from which to get the frame

index

Index of frame to get

Returns

pointer to GDrawCommandFrame at the specified index

GSize gdraw_command_sequence_get_bounds_size(GDrawCommandSequence * sequence)

Get the size of the bounding box surrounding all draw commands in the sequence. This bounding box can be used to set the graphics context or layer bounds when drawing the frames in the sequence.

Parameters

sequence

GDrawCommandSequence from which to get the bounds

Returns

bounding box size

void gdraw_command_sequence_set_bounds_size(GDrawCommandSequence * sequence, GSize size)

Set size of the bounding box surrounding all draw commands in the sequence. This bounding box can be used to set the graphics context or layer bounds when drawing the frames in the sequence.

Parameters

sequence

GDrawCommandSequence for which to set the bounds

size

bounding box size

uint32_t gdraw_command_sequence_get_play_count(GDrawCommandSequence * sequence)

Get the play count of the sequence.

Parameters

sequence

GDrawCommandSequence from which to get the play count

Returns

play count of sequence

void gdraw_command_sequence_set_play_count(GDrawCommandSequence * sequence, uint32_t play_count)

Set the play count of the sequence.

Parameters

sequence

GDrawCommandSequence for which to set the play count

play_count

play count

uint32_t gdraw_command_sequence_get_total_duration(GDrawCommandSequence * sequence)

Get the total duration of the sequence.

Parameters

sequence

GDrawCommandSequence from which to get the total duration

Returns

total duration of the sequence in milliseconds

uint32_t gdraw_command_sequence_get_num_frames(GDrawCommandSequence * sequence)

Get the number of frames in the sequence.

Parameters

sequence

GDrawCommandSequence from which to get the number of frames

Returns

number of frames in the sequence

GDrawCommandList * gdraw_command_frame_get_command_list(GDrawCommandFrame * frame)

Get the command list of the frame.

Parameters

frame

GDrawCommandFrame from which to get the command list

Returns

command list

Enum Documentation

enum GDrawCommandType

Enumerators

GDrawCommandTypeInvalid

Invalid draw command type.

GDrawCommandTypePath

Arbitrary path draw command type.

GDrawCommandTypeCircle

Circle draw command type.

GDrawCommandTypePrecisePath

Arbitrary path drawn with sub-pixel precision (1/8th precision)

Typedef Documentation

typedef struct GDrawCommandImage GDrawCommandImage

Draw command images contain a list of commands that can be drawn. An image can be loaded from PDC file data.

typedef struct GDrawCommand GDrawCommand

Draw commands are the basic building block of the draw command system, encoding the type of command to draw, the stroke width and color, fill color, and points that define the path (or center of a circle.

typedef struct GDrawCommandFrame GDrawCommandFrame

Draw command frames contain a list of commands to draw for that frame and a duration, indicating the length of time for which the frame should be drawn in an animation sequence. Frames form the building blocks of a GDrawCommandSequence, which consists of multiple frames.

typedef struct GDrawCommandList GDrawCommandList

Draw command lists contain a list of commands that can be iterated over and drawn all at once.

typedef struct GDrawCommandSequence GDrawCommandSequence

Draw command sequences allow the animation of frames over time. Each sequence has a list of frames that can be accessed by the elapsed duration of the animation (not maintained internally) or by index. Sequences can be loaded from PDC file data.

typedef bool(* GDrawCommandListIteratorCb)(GDrawCommand *command, uint32_t index, void *context)

Callback for iterating over draw command list.

Parameters

command

current GDrawCommand in iteration

index

index of the current command in the list

context

context pointer for the iteration operation

Returns

true if the iteration should continue after this command is processed

Need some help?

Functions

  • gdraw_command_draw
  • gdraw_command_get_type
  • gdraw_command_set_fill_color
  • gdraw_command_get_fill_color
  • gdraw_command_set_stroke_color
  • gdraw_command_get_stroke_color
  • gdraw_command_set_stroke_width
  • gdraw_command_get_stroke_width
  • gdraw_command_get_num_points
  • gdraw_command_set_point
  • gdraw_command_get_point
  • gdraw_command_set_radius
  • gdraw_command_get_radius
  • gdraw_command_set_path_open
  • gdraw_command_get_path_open
  • gdraw_command_set_hidden
  • gdraw_command_get_hidden
  • gdraw_command_frame_draw
  • gdraw_command_frame_set_duration
  • gdraw_command_frame_get_duration
  • gdraw_command_image_create_with_resource
  • gdraw_command_image_clone
  • gdraw_command_image_destroy
  • gdraw_command_image_draw
  • gdraw_command_image_get_bounds_size
  • gdraw_command_image_set_bounds_size
  • gdraw_command_image_get_command_list
  • gdraw_command_list_iterate
  • gdraw_command_list_draw
  • gdraw_command_list_get_command
  • gdraw_command_list_get_num_commands
  • gdraw_command_sequence_create_with_resource
  • gdraw_command_sequence_clone
  • gdraw_command_sequence_destroy
  • gdraw_command_sequence_get_frame_by_elapsed
  • gdraw_command_sequence_get_frame_by_index
  • gdraw_command_sequence_get_bounds_size
  • gdraw_command_sequence_set_bounds_size
  • gdraw_command_sequence_get_play_count
  • gdraw_command_sequence_set_play_count
  • gdraw_command_sequence_get_total_duration
  • gdraw_command_sequence_get_num_frames
  • gdraw_command_frame_get_command_list

Enums

  • GDrawCommandType

Typedefs

  • GDrawCommandImage
  • GDrawCommand
  • GDrawCommandFrame
  • GDrawCommandList
  • GDrawCommandSequence
  • GDrawCommandListIteratorCb

Getting Help

Do you have questions about the Pebble SDK?

Do you need some help understanding something on this page?

You can either take advantage of our awesome developer community and check out the SDK Help forums, or you can send us a message through the website!