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

Collaboration diagram for Graphics Types:

Modules
	Color Definitions

Classes
union	GColor8

struct	GPoint

struct	GSize
	Represents a 2-dimensional size. More...

struct	GRect

struct	GBitmapDataRowInfo

struct	GEdgeInsets

Macros
#define	GColorFromRGBA(red, green, blue, alpha)

#define	GColorFromRGB(red, green, blue) GColorFromRGBA(red, green, blue, 255)

#define	GColorFromHEX(v) GColorFromRGB(((v) >> 16) & 0xff, ((v) >> 8) & 0xff, ((v) & 0xff))

#define	COLOR_FALLBACK(color, bw) (color)

#define	PBL_IF_RECT_ELSE(if_true, if_false) (if_true)

#define	PBL_IF_ROUND_ELSE(if_true, if_false) (if_false)

#define	PBL_IF_BW_ELSE(if_true, if_false) (if_false)

#define	PBL_IF_COLOR_ELSE(if_true, if_false) (if_true)

#define	GPoint(x, y) ((GPoint){(x), (y)})
	Convenience macro to make a GPoint.

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

#define	GSize(w, h) ((GSize){(w), (h)})
	Convenience macro to make a GSize.

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

#define	GRect(x, y, w, h) ((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	PLAY_COUNT_INFINITE UINT32_MAX
	Repeat Sequence or animation indefinitely.

#define	PLAY_DURATION_INFINITE UINT32_MAX
	Duration of Sequence or animation is infinite.

#define	GEdgeInsets4(t, r, b, l) ((GEdgeInsets){.top = t, .right = r, .bottom = b, .left = l})
	helper for GEdgeInsets macro

#define	GEdgeInsets3(t, rl, b) ((GEdgeInsets){.top = t, .right = rl, .bottom = b, .left = rl})
	helper for GEdgeInsets macro

#define	GEdgeInsets2(tb, rl) ((GEdgeInsets){.top = tb, .right = rl, .bottom = tb, .left = rl})
	helper for GEdgeInsets macro

#define	GEdgeInsets1(trbl) ((GEdgeInsets){.top = trbl, .right = trbl, .bottom = trbl, .left = trbl})
	helper for GEdgeInsets macro

#define	GEdgeInsetsN(_1, _2, _3, _4, NAME, ...) NAME
	helper for GEdgeInsets macro

#define	GEdgeInsets(...) GEdgeInsetsN(__VA_ARGS__, GEdgeInsets4, GEdgeInsets3, GEdgeInsets2, GEdgeInsets1)(__VA_ARGS__)

Typedefs
typedef union GColor8	GColor8

typedef GColor8	GColor

typedef struct GPoint	GPoint

typedef struct GSize	GSize
	Represents a 2-dimensional size.

typedef struct GRect	GRect

typedef enum GBitmapFormat	GBitmapFormat
	The format of a GBitmap can either be 1-bit or 8-bit.

typedef struct GBitmap	GBitmap

typedef struct GBitmapSequence	GBitmapSequence

typedef enum GAlign	GAlign

typedef struct GContext	GContext

Enumerations
enum	GBitmapFormat { GBitmapFormat1Bit = 0, GBitmapFormat8Bit, GBitmapFormat1BitPalette, GBitmapFormat2BitPalette, GBitmapFormat4BitPalette, GBitmapFormat8BitCircular }
	The format of a GBitmap can either be 1-bit or 8-bit.

enum	GAlign { GAlignCenter, GAlignTopLeft, GAlignTopRight, GAlignTop, GAlignLeft, GAlignBottom, GAlignRight, GAlignBottomRight, GAlignBottomLeft }

enum	GCompOp { GCompOpAssign, GCompOpAssignInverted, GCompOpOr, GCompOpAnd, GCompOpClear, GCompOpSet }

Functions
bool	gcolor_equal (GColor8 x, GColor8 y)
	True if both colors are identical or both are invisible (i.e. both have alpha values of .a=0).

GColor8	gcolor_legible_over (GColor8 background_color)

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

bool	gsize_equal (const GSize size_a, const GSize size_b)

bool	grect_equal (const GRect const rect_a, const GRect const rect_b)

bool	grect_is_empty (const GRect *const rect)

void	grect_standardize (GRect *rect)

void	grect_clip (GRect const rect_to_clip, const GRect const rect_clipper)

bool	grect_contains_point (const GRect rect, const GPoint point)

GPoint	grect_center_point (const GRect *rect)

GRect	grect_crop (GRect rect, const int32_t crop_size_px)

uint16_t	gbitmap_get_bytes_per_row (const GBitmap *bitmap)

GBitmapFormat	gbitmap_get_format (const GBitmap *bitmap)

uint8_t *	gbitmap_get_data (const GBitmap *bitmap)

void	gbitmap_set_data (GBitmap bitmap, uint8_t data, GBitmapFormat format, uint16_t row_size_bytes, bool free_on_destroy)

GRect	gbitmap_get_bounds (const GBitmap *bitmap)

void	gbitmap_set_bounds (GBitmap *bitmap, GRect bounds)

GColor *	gbitmap_get_palette (const GBitmap *bitmap)

void	gbitmap_set_palette (GBitmap bitmap, GColor palette, bool free_on_destroy)

GBitmap *	gbitmap_create_with_resource (uint32_t resource_id)

GBitmap *	gbitmap_create_with_data (const uint8_t *data)

GBitmap *	gbitmap_create_as_sub_bitmap (const GBitmap *base_bitmap, GRect sub_rect)

GBitmap *	gbitmap_create_from_png_data (const uint8_t *png_data, size_t png_data_size)

GBitmap *	gbitmap_create_blank (GSize size, GBitmapFormat format)

GBitmap *	gbitmap_create_blank_with_palette (GSize size, GBitmapFormat format, GColor *palette, bool free_on_destroy)

GBitmap *	gbitmap_create_palettized_from_1bit (const GBitmap *src_bitmap)

void	gbitmap_destroy (GBitmap *bitmap)

GBitmapSequence *	gbitmap_sequence_create_with_resource (uint32_t resource_id)

bool	gbitmap_sequence_update_bitmap_next_frame (GBitmapSequence bitmap_sequence, GBitmap bitmap, uint32_t *delay_ms)

bool	gbitmap_sequence_update_bitmap_by_elapsed (GBitmapSequence bitmap_sequence, GBitmap bitmap, uint32_t elapsed_ms)

void	gbitmap_sequence_destroy (GBitmapSequence *bitmap_sequence)

bool	gbitmap_sequence_restart (GBitmapSequence *bitmap_sequence)

int32_t	gbitmap_sequence_get_current_frame_idx (GBitmapSequence *bitmap_sequence)

uint32_t	gbitmap_sequence_get_total_num_frames (GBitmapSequence *bitmap_sequence)

uint32_t	gbitmap_sequence_get_play_count (GBitmapSequence *bitmap_sequence)

void	gbitmap_sequence_set_play_count (GBitmapSequence *bitmap_sequence, uint32_t play_count)

GSize	gbitmap_sequence_get_bitmap_size (GBitmapSequence *bitmap_sequence)

GBitmapDataRowInfo	gbitmap_get_data_row_info (const GBitmap *bitmap, uint16_t y)

void	grect_align (GRect rect, const GRect inside_rect, const GAlign alignment, const bool clip)

GRect	grect_inset (GRect rect, GEdgeInsets insets)

Detailed Description

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

Macro Definition Documentation

◆ COLOR_FALLBACK

#define COLOR_FALLBACK	(	color,
		bw
	)	(color)

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.

◆ GColorFromHEX

#define GColorFromHEX ( v ) GColorFromRGB(((v) >> 16) & 0xff, ((v) >> 8) & 0xff, ((v) & 0xff))

Convert hex integer to GColor.

Parameters

v	Integer hex value (e.g. 0x64ff46)

Returns: GColor created from the hex value

◆ GColorFromRGB

#define GColorFromRGB	(	red,
		green,
		blue
	)	GColorFromRGBA(red, green, blue, 255)

Convert RGB to GColor.

Parameters

red	Red value from 0 - 255
green	Green value from 0 - 255
blue	Blue value from 0 - 255

Returns: GColor created from the RGB values

◆ GColorFromRGBA

#define GColorFromRGBA	(	red,
		green,
		blue,
		alpha
	)

Value:

  ((GColor8){ \
  .a = (uint8_t)(alpha) >> 6, \
  .r = (uint8_t)(red) >> 6, \
  .g = (uint8_t)(green) >> 6, \
  .b = (uint8_t)(blue) >> 6, \
  })

Convert RGBA to GColor.

Parameters

red	Red value from 0 - 255
green	Green value from 0 - 255
blue	Blue value from 0 - 255
alpha	Alpha value from 0 - 255

Returns: GColor created from the RGB values

◆ GEdgeInsets

#define GEdgeInsets ( ... ) GEdgeInsetsN(__VA_ARGS__, GEdgeInsets4, GEdgeInsets3, GEdgeInsets2, GEdgeInsets1)(__VA_ARGS__)

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}
See also
grect_insets

◆ PBL_IF_BW_ELSE

#define PBL_IF_BW_ELSE	(	if_true,
		if_false
	)	(if_false)

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.

◆ PBL_IF_COLOR_ELSE

#define PBL_IF_COLOR_ELSE	(	if_true,
		if_false
	)	(if_true)

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.

◆ PBL_IF_RECT_ELSE

#define PBL_IF_RECT_ELSE	(	if_true,
		if_false
	)	(if_true)

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.

◆ PBL_IF_ROUND_ELSE

#define PBL_IF_ROUND_ELSE	(	if_true,
		if_false
	)	(if_false)

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.

Typedef Documentation

◆ GAlign

typedef enum GAlign GAlign

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

See also: bitmap_layer_set_alignment()

◆ GPoint

typedef struct GPoint 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.

◆ GRect

typedef struct GRect GRect

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

Enumeration Type Documentation

◆ GAlign

enum GAlign

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

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.

◆ GCompOp

enum GCompOp

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.

See also: bitmap_layer_set_compositing_mode(); graphics_context_set_compositing_mode(); graphics_draw_bitmap_in_rect(); graphics_draw_rotated_bitmap()

Enumerator
GCompOpAssign	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.
GCompOpAssignInverted	Assign the inverted pixel values of the source image to the destination pixels, effectively replacing the previous values for those pixels. Note For bitmaps with a format different from GBitmapFormat1Bit, this mode is not supported and the resulting behavior is undefined.
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. Note For bitmaps with a format different from GBitmapFormat1Bit, this mode is not supported and the resulting behavior is undefined.
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. Note For bitmaps with a format different from GBitmapFormat1Bit, this mode is not supported and the resulting behavior is undefined.
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. Note For bitmaps with a format different from GBitmapFormat1Bit, this mode is not supported and the resulting behavior is undefined.
GCompOpSet	Sets the bits in the destination image, using the source image as mask. This mode is required to apply any transparency of your bitmap. Note 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.

Function Documentation

◆ gbitmap_create_as_sub_bitmap()

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

Parameters

[in]	base_bitmap	The bitmap that the sub-bitmap of which the image data will be used by the sub-bitmap
	sub_rect	The 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_create_blank()

GBitmap* gbitmap_create_blank	(	GSize	size,
		GBitmapFormat	format
	)

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

Parameters

size	The Pebble image dimensions as a GSize.
format	The GBitmapFormat the created image should be in.

Returns: A pointer to the GBitmap. NULL if the GBitmap could not be created

◆ gbitmap_create_blank_with_palette()

GBitmap* gbitmap_create_blank_with_palette	(	GSize	size,
		GBitmapFormat	format,
		GColor *	palette,
		bool	free_on_destroy
	)

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.

Parameters

size	The Pebble image dimensions as a GSize.
format	the GBitmapFormat the created image and palette should be in.
palette	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.
free_on_destroy	Set whether the palette data should be freed along with the bitmap data when the GBitmap is destroyed.

Returns: A Pointer to the GBitmap. NULL if the GBitmap could not be created.

◆ gbitmap_create_from_png_data()

GBitmap* gbitmap_create_from_png_data	(	const uint8_t *	png_data,
		size_t	png_data_size
	)

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.

Note: PNG decoding currently supports 1,2,4 and 8 bit palettized and grayscale images.

Parameters

png_data	PNG image data.
png_data_size	PNG image size in bytes.

Returns: A pointer to the GBitmap. NULL if the GBitmap could not be created

◆ gbitmap_create_palettized_from_1bit()

GBitmap* gbitmap_create_palettized_from_1bit ( const GBitmap * src_bitmap )

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.

Parameters

src_bitmap A GBitmap of format GBitmapFormat1Bit which is to be copied into a newly created GBitmap of format GBitmapFormat1BitPalettized.

Returns: The newly created 1-bit palettized GBitmap, or NULL if there is not sufficient space.

Note: The new bitmap does not depend on any data from src_bitmap, so src_bitmap can be freed without worry.

◆ gbitmap_create_with_data()

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

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

Returns: A pointer to the GBitmap. NULL if the GBitmap could not be created

◆ gbitmap_create_with_resource()

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_id The ID of the bitmap resource to load

Returns: A pointer to the GBitmap. NULL if the GBitmap could not be created

◆ gbitmap_destroy()

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

◆ gbitmap_get_bounds()

GRect gbitmap_get_bounds ( const GBitmap * bitmap )

Gets the bounds of the content for the GBitmap. This is set when loading the image or if changed by gbitmap_set_bounds.

Parameters

bitmap A pointer to the GBitmap to get the bounding box from.

Returns: The bounding box for the GBitmap.

See also: gbitmap_set_bounds

◆ gbitmap_get_bytes_per_row()

uint16_t gbitmap_get_bytes_per_row ( const GBitmap * bitmap )

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.

Parameters

bitmap A pointer to the GBitmap to get the bytes per row

Returns: The number of bytes per row of the GBitmap

See also: gbitmap_get_data

◆ gbitmap_get_data()

uint8_t* gbitmap_get_data ( const GBitmap * bitmap )

Get a pointer to the raw image data section of the given GBitmap as specified by the format of the bitmap.

Parameters

bitmap A pointer to the GBitmap to get the data

Returns: pointer to the raw image data for the GBitmap

See also: gbitmap_get_bytes_per_row; GBitmap

◆ gbitmap_get_data_row_info()

GBitmapDataRowInfo gbitmap_get_data_row_info	(	const GBitmap *	bitmap,
		uint16_t	y
	)

Provides information about a pixel data row

Parameters

bitmap	A pointer to the GBitmap to get row info
y	Absolute row number in the pixel data, independent from the bitmap's bounds

Returns: Description of the row

Note: 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.

See also: gbitmap_get_data

◆ gbitmap_get_format()

GBitmapFormat gbitmap_get_format ( const GBitmap * bitmap )

Get the GBitmapFormat for the GBitmap.

Parameters

bitmap A pointer to the GBitmap to get the format

Returns: The format of the given GBitmap.

◆ gbitmap_get_palette()

GColor* gbitmap_get_palette ( const GBitmap * bitmap )

Get the palette for the given GBitmap.

Parameters

bitmap A pointer to the GBitmap to get the palette from.

Returns: Pointer to a GColor array containing the palette colors.

See also: gbitmap_set_palette

◆ gbitmap_sequence_create_with_resource()

GBitmapSequence* gbitmap_sequence_create_with_resource ( uint32_t resource_id )

Creates a GBitmapSequence from the specified resource (APNG/PNG files)

Parameters

resource_id Resource to load and create GBitmapSequence from.

Returns: GBitmapSequence pointer if the resource was loaded, NULL otherwise

◆ gbitmap_sequence_destroy()

void gbitmap_sequence_destroy ( GBitmapSequence * bitmap_sequence )

Deletes the GBitmapSequence structure and frees any allocated memory/decoder_data

Parameters

bitmap_sequence Pointer to the bitmap sequence to free (delete)

◆ gbitmap_sequence_get_bitmap_size()

GSize gbitmap_sequence_get_bitmap_size ( GBitmapSequence * bitmap_sequence )

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

Parameters

bitmap_sequence Pointer to loaded bitmap sequence

Returns: Dimensions required to render the bitmap sequence to a GBitmap

◆ gbitmap_sequence_get_current_frame_idx()

int32_t gbitmap_sequence_get_current_frame_idx ( GBitmapSequence * bitmap_sequence )

This function gets the current frame number for the bitmap sequence

Parameters

bitmap_sequence Pointer to loaded bitmap sequence

Returns: index of current frame in the current loop of the bitmap sequence

◆ gbitmap_sequence_get_play_count()

uint32_t gbitmap_sequence_get_play_count ( GBitmapSequence * bitmap_sequence )

This function gets the play count (number of times to repeat) the bitmap sequence

Note: This value is initialized by the bitmap sequence data, and is modified by gbitmap_sequence_set_play_count

Parameters

bitmap_sequence Pointer to loaded bitmap sequence

Returns: Play count of bitmap sequence, PLAY_COUNT_INFINITE for infinite looping

◆ gbitmap_sequence_get_total_num_frames()

uint32_t gbitmap_sequence_get_total_num_frames ( GBitmapSequence * bitmap_sequence )

This function sets the total number of frames for the bitmap sequence

Parameters

bitmap_sequence Pointer to loaded bitmap sequence

Returns: number of frames contained in a single loop of the bitmap sequence

◆ gbitmap_sequence_restart()

bool gbitmap_sequence_restart ( GBitmapSequence * bitmap_sequence )

Restarts the GBitmapSequence to the first frame gbitmap_sequence_update_bitmap_next_frame

Parameters

bitmap_sequence Pointer to loaded bitmap sequence

Returns: True if sequence was restarted, false otherwise

◆ gbitmap_sequence_set_play_count()

void gbitmap_sequence_set_play_count	(	GBitmapSequence *	bitmap_sequence,
		uint32_t	play_count
	)

This function sets the play count (number of times to repeat) the bitmap sequence

Parameters

bitmap_sequence	Pointer to loaded bitmap sequence
play_count	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

◆ gbitmap_sequence_update_bitmap_by_elapsed()

bool gbitmap_sequence_update_bitmap_by_elapsed	(	GBitmapSequence *	bitmap_sequence,
		GBitmap *	bitmap,
		uint32_t	elapsed_ms
	)

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.

Parameters

bitmap_sequence	Pointer to loaded bitmap sequence
bitmap	Pointer to the initialized GBitmap in which to render the bitmap sequence
elapsed_ms	Elapsed time in milliseconds in the sequence relative to start

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

Note: GBitmap must be large enough to accommodate the bitmap_sequence image gbitmap_sequence_get_bitmap_size; This function is disabled for play_count 0

◆ gbitmap_sequence_update_bitmap_next_frame()

bool gbitmap_sequence_update_bitmap_next_frame	(	GBitmapSequence *	bitmap_sequence,
		GBitmap *	bitmap,
		uint32_t *	delay_ms
	)

Updates the contents of the bitmap sequence to the next frame and optionally returns the delay in milliseconds until the next frame.

Parameters

	bitmap_sequence	Pointer to loaded bitmap sequence
	bitmap	Pointer to the initialized GBitmap in which to render the bitmap sequence
[out]	delay_ms	If not NULL, returns the delay in milliseconds until the next frame.

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

Note: GBitmap must be large enough to accommodate the bitmap_sequence image gbitmap_sequence_get_bitmap_size

◆ gbitmap_set_bounds()

void gbitmap_set_bounds	(	GBitmap *	bitmap,
		GRect	bounds
	)

Set the bounds of the given GBitmap.

Parameters

bitmap	A pointer to the GBitmap to set the bounding box.
bounds	The bounding box to set.

See also: gbitmap_get_bounds

◆ gbitmap_set_data()

void gbitmap_set_data	(	GBitmap *	bitmap,
		uint8_t *	data,
		GBitmapFormat	format,
		uint16_t	row_size_bytes,
		bool	free_on_destroy
	)

Set the bitmap data for the given GBitmap.

Parameters

bitmap	A pointer to the GBitmap to set data to
data	A pointer to the bitmap data
format	the format of the bitmap data. If this is a palettized format, make sure that there is an accompanying call to gbitmap_set_palette.
row_size_bytes	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.
free_on_destroy	Set whether the data should be freed when the GBitmap is destroyed.

See also: gbitmap_destroy

◆ gbitmap_set_palette()

void gbitmap_set_palette	(	GBitmap *	bitmap,
		GColor *	palette,
		bool	free_on_destroy
	)

Set the palette for the given GBitmap.

Parameters

bitmap	A pointer to the GBitmap to set the palette to
palette	The palette to be used. Make sure that the palette is large enough for the bitmap's format.
free_on_destroy	Set whether the palette data should be freed when the GBitmap is destroyed or when another palette is set.

See also: gbitmap_get_format; gbitmap_destroy; gbitmap_set_palette

◆ gcolor_legible_over()

GColor8 gcolor_legible_over ( GColor8 background_color )

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.

Parameters

background_color Background color for the region in question

Returns: A legible color for the given background color

◆ gpoint_equal()

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

Tests whether 2 points are equal.

Parameters

point_a	Pointer to the first point
point_b	Pointer to the second point

Returns: true if both points are equal, false if not.

◆ grect_align()

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]	rect	The rectangle to align (in place)
[out]	rect	The aligned and optionally clipped rectangle
	inside_rect	The rectangle in which to align `rect`
	alignment	Determines the alignment of `rect` within `inside_rect` by specifying what edges of should overlap.
	clip	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.

◆ grect_center_point()

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

rect	The rectangle for which to calculate the center point.

Returns: The point at the center of rect

◆ grect_clip()

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_clip	The rectangle that needs to be clipped (in place).
[out]	rect_to_clip	The clipped rectangle.
	rect_clipper	The rectangle of which the edges will serve as "scissors" in order to trim `rect_to_clip`.

◆ grect_contains_point()

bool grect_contains_point	(	const GRect *	rect,
		const GPoint *	point
	)

Tests whether a rectangle contains a point.

Parameters

rect	The rectangle
point	The point

Returns: true if the rectangle contains the point, or false if it does not.

◆ grect_crop()

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

rect	The rectangle that will be inset
crop_size_px	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.

Returns: The cropped rectangle.

◆ grect_equal()

bool grect_equal	(	const GRect *const	rect_a,
		const GRect *const	rect_b
	)

Tests whether 2 rectangles are equal.

Parameters

rect_a	Pointer to the first rectangle
rect_b	Pointer to the second rectangle

Returns: true if both rectangles are equal, false if not.

◆ grect_inset()

GRect grect_inset	(	GRect	rect,
		GEdgeInsets	insets
	)

Returns a rectangle that is shrinked or expanded by the given edge insets.

Note: 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.

Parameters

rect	The rectangle that will be inset
insets	The insets that will be applied

Returns: The resulting rectangle

Note: 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));

◆ grect_is_empty()

bool grect_is_empty ( const GRect *const rect )

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

Parameters

rect	Pointer 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!

◆ grect_standardize()

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]	rect	The rectangle to convert.
[out]	rect	The standardized rectangle.

◆ gsize_equal()

bool gsize_equal	(	const GSize *	size_a,
		const GSize *	size_b
	)

Tests whether 2 sizes are equal.

Parameters

size_a	Pointer to the first size
size_b	Pointer to the second size

Returns: true if both sizes are equal, false if not.

Modules

Classes

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ COLOR_FALLBACK

◆ GColorFromHEX

◆ GColorFromRGB

◆ GColorFromRGBA

◆ GEdgeInsets

◆ PBL_IF_BW_ELSE

◆ PBL_IF_COLOR_ELSE

◆ PBL_IF_RECT_ELSE

◆ PBL_IF_ROUND_ELSE

Typedef Documentation

◆ GAlign

◆ GPoint

◆ GRect

Enumeration Type Documentation

◆ GAlign

◆ GCompOp

Function Documentation

◆ gbitmap_create_as_sub_bitmap()

◆ gbitmap_create_blank()

◆ gbitmap_create_blank_with_palette()

◆ gbitmap_create_from_png_data()

◆ gbitmap_create_palettized_from_1bit()

◆ gbitmap_create_with_data()

◆ gbitmap_create_with_resource()

◆ gbitmap_destroy()

◆ gbitmap_get_bounds()

◆ gbitmap_get_bytes_per_row()

◆ gbitmap_get_data()

◆ gbitmap_get_data_row_info()

◆ gbitmap_get_format()

◆ gbitmap_get_palette()

◆ gbitmap_sequence_create_with_resource()

◆ gbitmap_sequence_destroy()

◆ gbitmap_sequence_get_bitmap_size()

◆ gbitmap_sequence_get_current_frame_idx()

◆ gbitmap_sequence_get_play_count()

◆ gbitmap_sequence_get_total_num_frames()

◆ gbitmap_sequence_restart()

◆ gbitmap_sequence_set_play_count()

◆ gbitmap_sequence_update_bitmap_by_elapsed()

◆ gbitmap_sequence_update_bitmap_next_frame()

◆ gbitmap_set_bounds()

◆ gbitmap_set_data()

◆ gbitmap_set_palette()

◆ gcolor_legible_over()

◆ gpoint_equal()

◆ grect_align()

◆ grect_center_point()

◆ grect_clip()

◆ grect_contains_point()

◆ grect_crop()

◆ grect_equal()

◆ grect_inset()

◆ grect_is_empty()

◆ grect_standardize()

◆ gsize_equal()