All Data Structures Functions Variables Typedefs Enumerations Enumerator Groups
Graphics Types

Detailed Description

Basic graphics types (point, rect, size, color, bitmaps, etc.) and utility functions.

Function Documentation

GBitmap* gbitmap_create_as_sub_bitmap ( const GBitmap base_bitmap,
GRect  sub_rect 
)

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 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 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().

Parameters
[in]base_bitmapThe bitmap that the sub-bitmap of which the image data will be used by the sub-bitmap
sub_rectThe rectangle within the image data of the base bitmap. The bounds of the base bitmap will be used to clip sub_rect.
Returns
A pointer to the GBitmap. NULL if the GBitmap could not be created
GBitmap* gbitmap_create_blank ( GSize  size)

Creates a new blank GBitmap on the heap initialized to zeroes. The resulting GBitmap must be destroyed using gbitmap_destroy().

Parameters
sizeThe Pebble image dimensions as a GSize.
Returns
A pointer to the GBitmap. NULL if the GBitmap could not be created
GBitmap* gbitmap_create_with_data ( const uint8_t *  data)

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.

Note
One way to generate Pebble image data is to use bitmapgen.py in the Pebble SDK to generate a .pbi file.
Parameters
dataThe 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.
Returns
A pointer to the GBitmap. NULL if the GBitmap could not be created
GBitmap* gbitmap_create_with_resource ( uint32_t  resource_id)

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().

Parameters
resource_idThe ID of the bitmap resource to load
Returns
A pointer to the GBitmap. NULL if the GBitmap could not be created
void gbitmap_destroy ( GBitmap bitmap)

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().

bool gpoint_equal ( const GPoint *const  point_a,
const GPoint *const  point_b 
)

Tests whether 2 points are equal.

Parameters
point_aPointer to the first point
point_bPointer to the second point
Returns
true if both points are equal, false if not.
void grect_align ( GRect rect,
const GRect inside_rect,
const GAlign  alignment,
const bool  clip 
)

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.

Parameters
[in]rectThe rectangle to align (in place)
[out]rectThe aligned and optionally clipped rectangle
inside_rectThe rectangle in which to align rect
alignmentDetermines the alignment of rect within inside_rect by specifying what edges of should overlap.
clipDetermines 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.
GPoint grect_center_point ( const GRect rect)

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).

Parameters
rectThe rectangle for which to calculate the center point.
Returns
The point at the center of rect
void grect_clip ( GRect *const  rect_to_clip,
const GRect *const  rect_clipper 
)

Trim one rectangle using the edges of a second rectangle.

Parameters
[in]rect_to_clipThe rectangle that needs to be clipped (in place).
[out]rect_to_clipThe clipped rectangle.
rect_clipperThe rectangle of which the edges will serve as "scissors" in order to trim rect_to_clip.
bool grect_contains_point ( const GRect rect,
const GPoint point 
)

Tests whether a rectangle contains a point.

Parameters
rectThe rectangle
pointThe point
Returns
true if the rectangle contains the point, or false if it does not.
GRect grect_crop ( GRect  rect,
const int32_t  crop_size_px 
)

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.

Note
The function will trip an assertion if the crop yields a rectangle with negative width or height.
Parameters
rectThe rectangle that will be inset
crop_size_pxThe 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.
Returns
The cropped rectangle.
bool grect_equal ( const GRect *const  rect_a,
const GRect *const  rect_b 
)

Tests whether 2 rectangles are equal.

Parameters
rect_aPointer to the first rectangle
rect_bPointer to the second rectangle
Returns
true if both rectangles are equal, false if not.
bool grect_is_empty ( const GRect *const  rect)

Tests whether the size of the rectangle is (0, 0).

Parameters
rectPointer to the rectangle
Returns
true if the rectangle its size is (0, 0), or false if not.
Note
If the width and/or height of a rectangle is negative, this function will return true!
void grect_standardize ( GRect rect)

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).

Parameters
[in]rectThe rectangle to convert.
[out]rectThe standardized rectangle.
bool gsize_equal ( const GSize size_a,
const GSize size_b 
)

Tests whether 2 sizes are equal.

Parameters
size_aPointer to the first size
size_bPointer to the second size
Returns
true if both sizes are equal, false if not.

Data Structure Documentation

struct GBitmap

Structure containing the metadata of a bitmap image.

Note that this structure does NOT contain any pixel data; it only has a pointer to a buffer containing the pixels (the addr field). The metadata describes how long each row of pixels is in the buffer (the stride). Each row must be a multiple of 32 pixels (4 bytes). Using the bounds field, the area that is actually relevant can be specified.

For example, when the image is 29 by 5 pixels (width by height) and the first bit of image data is the pixel at (0, 0), then the bounds.size would be GSize(29, 5) and bounds.origin would be GPoint(0, 0).

gbitmap.png

In the illustration each pixel is a representated as a square. The white squares are the bits that are used, the gray squares are the padding bits, because each row of image data has to be a multiple of 4 bytes (32 bits). The numbers in the column in the left are the offsets (in bytes) from the *addr field of the GBitmap.

Each pixel in a bitmap is represented by 1 bit. If a bit is set (1 or true), it will result in a white pixel, and vice versa, if a bit is cleared (0 or false), it will result in a black pixel.

pixel_bit_values.png
See Also
BitmapLayer
graphics_draw_bitmap_in_rect
Resources
Data Fields
union GBitmap __unnamed__ Private attributes used by the system.
void * addr Pointer to the address where the image data lives.
GRect bounds The box of bits that the addr field is pointing to, that contains the actual image data to use. Note that this may be a subsection of the data with padding on all sides.
uint16_t row_size_bytes
Note
The number of bytes per row should be a multiple of 4. Also, the following should (naturally) be true: (row_size_bytes * 8 >= bounds.w)
union GBitmap.__unnamed__

Private attributes used by the system.

Data Fields
__unnamed__ __unnamed__
uint16_t info_flags Bitfields of metadata flags.
struct GPoint

Represents a point in a 2-dimensional coordinate system.

Note
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.
Data Fields
int16_t x The x-coordinate.
int16_t y The y-coordinate.
struct GRect

Represents a rectangle and defining it using the origin of the upper-lefthand corner and its size.

Data Fields
GPoint origin The coordinate of the upper-lefthand corner point of the rectangle.
GSize size The size of the rectangle.
struct GSize

Represents a 2-dimensional size.

Data Fields
int16_t h The height.
int16_t w The width.

Enumeration Type Documentation

enum GAlign

Values to specify how two things should be aligned relative to each other.

galign.png
.

See Also
bitmap_layer_set_alignment()
Enumerator
GAlignCenter 

Align by centering.

GAlignTopLeft 

Align by making the top edges overlap and left edges overlap.

GAlignTopRight 

Align by making the top edges overlap and left edges overlap.

GAlignTop 

Align by making the top edges overlap and centered horizontally.

GAlignLeft 

Align by making the left edges overlap and centered vertically.

GAlignBottom 

Align by making the bottom edges overlap and centered horizontally.

GAlignRight 

Align by making the right edges overlap and centered vertically.

GAlignBottomRight 

Align by making the bottom edges overlap and right edges overlap.

GAlignBottomLeft 

Align by making the bottom edges overlap and left edges overlap.

enum GColor

Color values.

Enumerator
GColorClear 

Represents "clear" or transparent.

GColorBlack 

Represents black.

GColorWhite 

Represents white.

enum GCompOp

Values to specify how the source image should be composited onto the destination image.

There is no notion of "transparency" in the graphics system. However, the effect of transparency can be created by masking and using compositing modes.

compops.png

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".

See Also
bitmap_layer_set_compositing_mode()
graphics_context_set_compositing_mode()
graphics_draw_bitmap_in_rect()
Enumerator
GCompOpAssign 

Assign the pixel values of the source image to the destination pixels, effectively replacing the previous values for those pixels.

GCompOpAssignInverted 

Assign the inverted pixel values of the source image to the destination pixels, effectively replacing the previous values for those pixels.

GCompOpOr 

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.

GCompOpAnd 

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.

GCompOpClear 

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.

GCompOpSet 

Sets 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 black, the destination image will be painted white. Other parts will be left untouched.

Macro Definition Documentation

#define GPoint (   x,
 
)    ((GPoint){(x), (y)})

Convenience macro to make a GPoint.

#define GPointZero   GPoint(0, 0)

Convenience macro to make a GPoint at (0, 0).

#define GRect (   x,
  y,
  w,
 
)    ((GRect){{(x), (y)}, {(w), (h)}})

Convenience macro to make a GRect.

#define GRectZero   GRect(0, 0, 0, 0)

Convenience macro to make a GRect of ((0, 0), (0, 0)).

#define GSize (   w,
 
)    ((GSize){(w), (h)})

Convenience macro to make a GSize.

#define GSizeZero   GSize(0, 0)

Convenience macro to make a GSize of (0, 0).