Basic graphics types (point, rect, size, color, bitmaps, etc.) and utility functions.
A list of all of the named colors available with links to the color map on the Pebble Developer website.
Comparison function for GColors.
True if both colors are identical or both are invisible (i.e. both have alpha values of .a=0).
This method assists in improving the legibility of text on various background colors. It takes the background color for the region in question and computes a color for maximum legibility.
Background color for the region in question
A legible color for the given background color
Tests whether the size of the rectangle is (0, 0).
If the width and/or height of a rectangle is negative, this function will return true
!
Pointer to the rectangle
true
if the rectangle its size is (0, 0), or false
if not.
Converts a rectangle's values so that the components of its size (width and/or height) are both positive. In the width and/or height are negative, the origin will offset, so that the final rectangle overlaps with the original. For example, a GRect with size (-10, -5) and origin (20, 20), will be standardized to size (10, 5) and origin (10, 15).
The rectangle to convert.
The standardized rectangle.
Trim one rectangle using the edges of a second rectangle.
The rectangle that needs to be clipped (in place).
The clipped rectangle.
The rectangle of which the edges will serve as "scissors" in order to trim rect_to_clip
.
Convenience function to compute the center-point of a given rectangle. This is equal to (rect->x + rect->width / 2, rect->y + rect->height / 2)
.
The rectangle for which to calculate the center point.
The point at the center of rect
Reduce the width and height of a rectangle by insetting each of the edges with a fixed inset. The returned rectangle will be centered relative to the input rectangle.
The function will trip an assertion if the crop yields a rectangle with negative width or height.
The rectangle that will be inset
The inset by which each of the rectangle will be inset. A positive inset value results in a smaller rectangle, while negative inset value results in a larger rectangle.
The cropped rectangle.
Get the number of bytes per row in the bitmap data for the given GBitmap. On rectangular displays, this can be used as a safe way of iterating over the rows in the bitmap, since bytes per row should be set according to format. On circular displays with pixel format of GBitmapFormat8BitCircular this will return 0, and should not be used for iteration over frame buffer pixels. Instead, use GBitmapDataRowInfo, which provides safe minimum and maximum x values for a given row's y value.
A pointer to the GBitmap to get the bytes per row
The number of bytes per row of the GBitmap
Get the GBitmapFormat for the GBitmap.
A pointer to the GBitmap to get the format
The format of the given GBitmap.
Get a pointer to the raw image data section of the given GBitmap as specified by the format of the bitmap.
A pointer to the GBitmap to get the data
pointer to the raw image data for the GBitmap
Set the bitmap data for the given GBitmap.
A pointer to the GBitmap to set data to
A pointer to the bitmap data
the format of the bitmap data. If this is a palettized format, make sure that there is an accompanying call to gbitmap_set_palette.
How many bytes a single row takes. For example, bitmap data of format GBitmapFormat1Bit must have a row size as a multiple of 4 bytes.
Set whether the data should be freed when the GBitmap is destroyed.
Gets the bounds of the content for the GBitmap. This is set when loading the image or if changed by gbitmap_set_bounds.
A pointer to the GBitmap to get the bounding box from.
The bounding box for the GBitmap.
Set the bounds of the given GBitmap.
A pointer to the GBitmap to set the bounding box.
The bounding box to set.
Get the palette for the given GBitmap.
A pointer to the GBitmap to get the palette from.
Pointer to a GColor array containing the palette colors.
Set the palette for the given GBitmap.
A pointer to the GBitmap to set the palette to
The palette to be used. Make sure that the palette is large enough for the bitmap's format.
Set whether the palette data should be freed when the GBitmap is destroyed or when another palette is set.
Creates a new GBitmap on the heap using a Pebble image file stored as a resource. The resulting GBitmap must be destroyed using gbitmap_destroy().
The ID of the bitmap resource to load
A pointer to the GBitmap. NULL
if the GBitmap could not be created
Creates a new GBitmap on the heap initialized with the provided Pebble image data.
The resulting GBitmap must be destroyed using gbitmap_destroy() but the image data will not be freed automatically. The developer is responsible for keeping the image data in memory as long as the bitmap is used and releasing it after the bitmap is destroyed.
One way to generate Pebble image data is to use bitmapgen.py in the Pebble SDK to generate a .pbi file.
The Pebble image data. Must not be NULL. The function assumes the data to be correct; there are no sanity checks performed on the data. The data will not be copied and the pointer must remain valid for the lifetime of this GBitmap.
A pointer to the GBitmap. NULL
if the GBitmap could not be created
Create a new GBitmap on the heap as a sub-bitmap of a 'base' GBitmap, using a GRect to indicate what portion of the base to use. The sub-bitmap will just reference the image data and palette of the base bitmap. No deep-copying occurs as a result of calling this function, thus the caller is responsible for making sure the base bitmap and palette will remain available when using the sub-bitmap. Note that you should not destroy the parent bitmap until the sub_bitmap has been destroyed. The resulting GBitmap must be destroyed using gbitmap_destroy().
The bitmap that the sub-bitmap of which the image data will be used by the sub-bitmap
The rectangle within the image data of the base bitmap. The bounds of the base bitmap will be used to clip sub_rect
.
A pointer to the GBitmap. NULL
if the GBitmap could not be created
Create a GBitmap based on raw PNG data. The resulting GBitmap must be destroyed using gbitmap_destroy(). The developer is responsible for freeing png_data following this call.
PNG decoding currently supports 1,2,4 and 8 bit palettized and grayscale images.
PNG image data.
PNG image size in bytes.
A pointer to the GBitmap. NULL
if the GBitmap could not be created
Creates a new blank GBitmap on the heap initialized to zeroes. In the case that the format indicates a palettized bitmap, a palette of appropriate size will also be allocated on the heap. The resulting GBitmap must be destroyed using gbitmap_destroy().
The Pebble image dimensions as a GSize.
The GBitmapFormat the created image should be in.
A pointer to the GBitmap. NULL
if the GBitmap could not be created
Creates a new blank GBitmap on the heap, initialized to zeroes, and assigns it the given palette. No deep-copying of the palette occurs, so the caller is responsible for making sure the palette remains available when using the resulting bitmap. Management of that memory can be handed off to the system with the free_on_destroy argument.
The Pebble image dimensions as a GSize.
the GBitmapFormat the created image and palette should be in.
a pointer to a palette that is to be used for this GBitmap. The palette should be large enough to hold enough colors for the specified format. For example, GBitmapFormat2BitPalette should have 4 colors, since 2^2 = 4.
Set whether the palette data should be freed along with the bitmap data when the GBitmap is destroyed.
A Pointer to the GBitmap. NULL
if the GBitmap could not be created.
Given a 1-bit GBitmap, create a new bitmap of format GBitmapFormat1BitPalette. The new data buffer is allocated on the heap, and a 2-color palette is allocated as well.
The new bitmap does not depend on any data from src_bitmap, so src_bitmap can be freed without worry.
A GBitmap of format GBitmapFormat1Bit which is to be copied into a newly created GBitmap of format GBitmapFormat1BitPalettized.
The newly created 1-bit palettized GBitmap, or NULL if there is not sufficient space.
Destroy a GBitmap. This must be called for every bitmap that's been created with gbitmap_create_*.
This function will also free the memory of the bitmap data (bitmap->addr) if the bitmap was created with gbitmap_create_blank() or gbitmap_create_with_resource().
If the GBitmap was created with gbitmap_create_with_data(), you must release the memory after calling gbitmap_destroy().
Creates a GBitmapSequence from the specified resource (APNG/PNG files)
Resource to load and create GBitmapSequence from.
GBitmapSequence pointer if the resource was loaded, NULL otherwise
Updates the contents of the bitmap sequence to the next frame and optionally returns the delay in milliseconds until the next frame.
GBitmap must be large enough to accommodate the bitmap_sequence image gbitmap_sequence_get_bitmap_size
Pointer to loaded bitmap sequence
Pointer to the initialized GBitmap in which to render the bitmap sequence
If not NULL, returns the delay in milliseconds until the next frame.
True if frame was rendered. False if all frames (and loops) have been rendered for the sequence. Will also return false if frame could not be rendered (includes out of memory errors).
Updates the contents of the bitmap sequence to the frame at elapsed in the sequence. For looping animations this accounts for the loop, for example an animation of 1 second that is configured to loop 2 times updated to 1500 ms elapsed time will display the sequence frame at 500 ms. Elapsed time is the time from the start of the animation, and will be ignored if it is for a time earlier than the last rendered frame.
GBitmap must be large enough to accommodate the bitmap_sequence image gbitmap_sequence_get_bitmap_size
This function is disabled for play_count 0
Pointer to loaded bitmap sequence
Pointer to the initialized GBitmap in which to render the bitmap sequence
Elapsed time in milliseconds in the sequence relative to start
True if a frame was rendered. False if all frames (and loops) have already been rendered for the sequence. Will also return false if frame could not be rendered (includes out of memory errors).
Deletes the GBitmapSequence structure and frees any allocated memory/decoder_data.
Pointer to the bitmap sequence to free (delete)
Restarts the GBitmapSequence to the first frame gbitmap_sequence_update_bitmap_next_frame.
Pointer to loaded bitmap sequence
True if sequence was restarted, false otherwise
This function gets the current frame number for the bitmap sequence.
Pointer to loaded bitmap sequence
index of current frame in the current loop of the bitmap sequence
This function sets the total number of frames for the bitmap sequence.
Pointer to loaded bitmap sequence
number of frames contained in a single loop of the bitmap sequence
This function gets the play count (number of times to repeat) the bitmap sequence.
This value is initialized by the bitmap sequence data, and is modified by gbitmap_sequence_set_play_count
Pointer to loaded bitmap sequence
Play count of bitmap sequence, PLAY_COUNT_INFINITE for infinite looping
This function sets the play count (number of times to repeat) the bitmap sequence.
Pointer to loaded bitmap sequence
Number of times to repeat the bitmap sequence with 0 disabling update_by_elapsed and update_next_frame, and PLAY_COUNT_INFINITE for infinite looping of the animation
This function gets the minimum required size (dimensions) necessary to render the bitmap sequence to a GBitmap using the /ref gbitmap_sequence_update_bitmap_next_frame.
Pointer to loaded bitmap sequence
Dimensions required to render the bitmap sequence to a GBitmap
Provides information about a pixel data row.
This function does not respect the bitmap's bounds but purely operates on the pixel data. This function works with every bitmap format including GBitmapFormat1Bit. The result of the function for invalid rows is undefined.
A pointer to the GBitmap to get row info
Absolute row number in the pixel data, independent from the bitmap's bounds
Description of the row
Aligns one rectangle within another rectangle, using an alignment parameter. The relative coordinate systems of both rectangles are assumed to be the same. When clip is true, rect
is also clipped by the constraint.
The rectangle to align (in place)
The aligned and optionally clipped rectangle
The rectangle in which to align rect
Determines the alignment of rect
within inside_rect
by specifying what edges of should overlap.
Determines whether rect
should be trimmed using the edges of inside_rect
in case rect
extends outside of the area that inside_rect
covers after the alignment.
Returns a rectangle that is shrinked or expanded by the given edge insets.
The rectangle is standardized and then the inset parameters are applied. If the resulting rectangle would have a negative height or width, a GRectZero is returned.
Use this function in together with the GEdgeInsets macro
GRect r_inset_all_sides = grect_inset(r, GEdgeInsets(10));
GRect r_inset_vertical_horizontal = grect_inset(r, GEdgeInsets(10, 20));
GRect r_expand_top_right_shrink_bottom_left = grect_inset(r, GEdgeInsets(-10, -10, 10, 10));
The rectangle that will be inset
The insets that will be applied
The resulting rectangle
Description of a single data row in the pixel data of a bitmap.
This data type describes the actual pixel data of a bitmap and does not respect the bitmap's bounds.
Address of the byte at column 0 of a given data row in a bitmap. Use this to calculate the memory address of a pixel. For GBitmapFormat8BitCircular or GBitmapFormat8Bit this would be: uint8_t *pixel_addr = row_info.addr + x
. Note that this byte can be outside of the valid range for this row. For example: The first valid pixel (min_x=76
) of a row might start at 76 bytes after the given data pointer (assuming that 1 pixel is represented as 1 byte as in GBitmapFormat8BitCircular or GBitmapFormat8Bit).
The absolute column of a first valid pixel for a given data row.
The absolute column of the last valid pixel for a given data row. For optimization reasons the result can be anywhere between grect_get_max_x(bitmap_bounds) - 1 and the physical data boundary.
Represents insets for four sides. Negative values mean a side extends.
The inset at the top of an object.
The inset at the right of an object.
The inset at the bottom of an object.
The inset at the left of an object.
Represents a point in a 2-dimensional coordinate system.
Conventionally, the origin of Pebble's 2D coordinate system is in the upper, lefthand corner its x-axis extends to the right and its y-axis extends to the bottom of the screen.
The x-coordinate.
The y-coordinate.
Represents a 2-dimensional size.
The width.
The height.
The format of a GBitmap can either be 1-bit or 8-bit.
Values to specify how two things should be aligned relative to each other.
Align by centering.
Align by making the top edges overlap and left edges overlap.
Align by making the top edges overlap and left edges overlap.
Align by making the top edges overlap and centered horizontally.
Align by making the left edges overlap and centered vertically.
Align by making the bottom edges overlap and centered horizontally.
Align by making the right edges overlap and centered vertically.
Align by making the bottom edges overlap and right edges overlap.
Align by making the bottom edges overlap and left edges overlap.
Values to specify how the source image should be composited onto the destination image.
For Aplite, there is no notion of "transparency" in the graphics system. However, the effect of transparency can be created by masking and using compositing modes.
Contrived example of how the different compositing modes affect drawing. Often, the "destination image" is the render buffer and thus contains the image of what has been drawn before or "underneath".
For Basalt, at the moment, only two compositing modes are supported, GCompOpAssign and GCompOpSet. The behavior of other compositing modes are undefined and may change in the future. Transparency can be achieved using GCompOpSet and requires pixel values with alpha value .a < 3.
Assign the pixel values of the source image to the destination pixels, effectively replacing the previous values for those pixels. For Basalt, when drawing a color palettized or 8-bit GBitmap image, the opacity value is ignored.
For Basalt, this mode is not supported and the resulting behavior is undefined.
Assign the inverted pixel values of the source image to the destination pixels, effectively replacing the previous values for those pixels.
For Basalt, this mode is not supported and the resulting behavior is undefined.
Use the boolean operator OR
to composite the source and destination pixels. The visual result of this compositing mode is the source's white pixels are painted onto the destination and the source's black pixels are treated as clear.
For Basalt, this mode is not supported and the resulting behavior is undefined.
Use the boolean operator AND
to composite the source and destination pixels. The visual result of this compositing mode is the source's black pixels are painted onto the destination and the source's white pixels are treated as clear.
For Basalt, this mode is not supported and the resulting behavior is undefined.
Clears the bits in the destination image, using the source image as mask. The visual result of this compositing mode is that for the parts where the source image is white, the destination image will be painted black. Other parts will be left untouched.
Sets the bits in the destination image, using the source image as mask. For Aplite, the visual result of this compositing mode is that for the parts where the source image is black, the destination image will be painted white. Other parts will be left untouched. For Basalt, when drawing a color palettized or 8-bit GBitmap image, this mode will be required to apply any transparency.
Values to specify how the source image should be composited onto the destination image.
Contrived example of how the different compositing modes affect drawing. Often, the "destination image" is the render buffer and thus contains the image of what has been drawn before or "underneath".
For color displays, only two compositing modes are supported, GCompOpAssign and GCompOpSet. The behavior of other compositing modes are undefined and may change in the future. Transparency can be achieved using GCompOpSet and requires pixel values with alpha value .a < 3.
Assign the pixel values of the source image to the destination pixels, effectively replacing the previous values for those pixels. For color displays, when drawing a palettized or 8-bit GBitmap image, the opacity value is ignored.
For bitmaps with a format different from GBitmapFormat1Bit, this mode is not supported and the resulting behavior is undefined.
Assign the inverted pixel values of the source image to the destination pixels, effectively replacing the previous values for those pixels.
For bitmaps with a format different from GBitmapFormat1Bit, this mode is not supported and the resulting behavior is undefined.
Use the boolean operator OR
to composite the source and destination pixels. The visual result of this compositing mode is the source's white pixels are painted onto the destination and the source's black pixels are treated as clear.
For bitmaps with a format different from GBitmapFormat1Bit, this mode is not supported and the resulting behavior is undefined.
Use the boolean operator AND
to composite the source and destination pixels. The visual result of this compositing mode is the source's black pixels are painted onto the destination and the source's white pixels are treated as clear.
For bitmaps with a format different from GBitmapFormat1Bit, this mode is not supported and the resulting behavior is undefined.
Clears the bits in the destination image, using the source image as mask. The visual result of this compositing mode is that for the parts where the source image is white, the destination image will be painted black. Other parts will be left untouched.
For bitmaps of the format GBitmapFormat1Bit, the visual result of this compositing mode is that for the parts where the source image is black, the destination image will be painted white. Other parts will be left untouched.
Sets the bits in the destination image, using the source image as mask. This mode is required to apply any transparency of your bitmap.
Convert RGBA to GColor.
Red value from 0 - 255
Green value from 0 - 255
Blue value from 0 - 255
Alpha value from 0 - 255
GColor created from the RGB values
Convert RGB to GColor.
Red value from 0 - 255
Green value from 0 - 255
Blue value from 0 - 255
GColor created from the RGB values
Convert hex integer to GColor.
Integer hex value (e.g. 0x64ff46)
GColor created from the hex value
Convenience macro allowing use of a fallback color for black and white platforms. On color platforms, the first expression will be chosen, the second otherwise.
Convenience macro allowing use of a fallback color for black and white platforms. On color platforms, the first expression will be chosen, the second otherwise.
Convenience macro to switch between two expression depending on the screen of the platform. On platforms with rectangular screen, the first expression will be chosen, the second otherwise.
Convenience macro to switch between two expression depending on the screen of the platform. On platforms with round screen, the first expression will be chosen, the second otherwise.
Convenience macro to switch between two expression depending on the screen of the platform. On black& white platforms, the first expression will be chosen, the second otherwise.
Convenience macro to switch between two expression depending on the screen of the platform. On black& white platforms, the first expression will be chosen, the second otherwise.
Convenience macro to switch between two expression depending on the screen of the platform. On color platforms, the first expression will be chosen, the second otherwise.
Convenience macro to switch between two expression depending on the screen of the platform. On color platforms, the first expression will be chosen, the second otherwise.
Convenience macro to make a GPoint.
Convenience macro to make a GSize.
Convenience macro to make a GRect.
Repeat Sequence or animation indefinitely.
Duration of Sequence or animation is infinite.
helper for GEdgeInsets macro
helper for GEdgeInsets macro
helper for GEdgeInsets macro
helper for GEdgeInsets macro
helper for GEdgeInsets macro
Convenience macro to make a GEdgeInsets This macro follows the CSS shorthand notation where you can call it with.
just one value GEdgeInsets(v1) to configure all edges with v1 (GEdgeInsets){.top = v1, .right = v1, .bottom = v1, .left = v1}
two values v1, v2 to configure a vertical and horizontal inset as (GEdgeInsets){.top = v1, .right = v2, .bottom = v1, .left = v2}
three values v1, v2, v3 to configure it with (GEdgeInsets){.top = v1, .right = v2, .bottom = v3, .left = v2}
four values v1, v2, v3, v4 to configure it with (GEdgeInsets){.top = v1, .right = v2, .bottom = v3, .left = v4}
grect_insets
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!