Compositor

Composes the app framebuffer and modal windows into the display framebuffer. More...

Modules
	Display flush
	Copies the dirty region of the system framebuffer to the display driver.
	Transitions
	Ready-made compositor transitions and helpers to build new ones.
	Default transitions
	Compositor transitions of the current design.
	Legacy transitions
	Slide transitions used on 1-bit displays.
	Screenshot protocol
	Pebble Protocol endpoint that sends the system framebuffer to the phone.

Data Structures
struct	CompositorTransition
	Implementation of a compositor transition animation. More...

Typedefs
typedef void(*	CompositorTransitionInitFunc) (Animation *animation)
	Set up the transition animation.
typedef void(*	CompositorTransitionUpdateFunc) (GContext *ctx, Animation *animation, uint32_t distance_normalized)
	Draw one frame of a transition.
typedef void(*	CompositorTransitionTeardownFunc) (Animation *animation)
	Clean up after a transition finished or was cancelled.
typedef struct FrameBuffer	FrameBuffer
	Opaque framebuffer type, see applib/graphics/framebuffer.h.
typedef void(*	CompositorFrozenCallback) (void *data)
	Called once the compositor is frozen.

Enumerations
enum	CompositorTransitionDirection {   CompositorTransitionDirectionUp , CompositorTransitionDirectionDown , CompositorTransitionDirectionLeft , CompositorTransitionDirectionRight ,   CompositorTransitionDirectionNone }
	Transition direction, from the current position to the next. More...

Functions
void	compositor_init (void)
	Initialize the compositor.
void	compositor_transition (const CompositorTransition *impl)
	Start a transition.
void	compositor_transition_render (CompositorTransitionUpdateFunc func, Animation *animation, const AnimationProgress distance_normalized)
	Render one transition frame with the given update function.
void	compositor_render_app (void)
	Write the app framebuffer into the system framebuffer.
void	compositor_render_modal (void)
	Render the modal window stack into the system framebuffer.
void	compositor_modal_render_ready (void)
	Notify that the modal needs to redraw itself to the display.
void	compositor_app_render_ready (void)
	Notify that the app has a new frame for the display.
FrameBuffer *	compositor_get_framebuffer (void)
	Get the system framebuffer.
GBitmap	compositor_get_framebuffer_as_bitmap (void)
	Get the system framebuffer as a bitmap.
GBitmap	compositor_get_app_framebuffer_as_bitmap (void)
	Get the app framebuffer as a bitmap.
bool	compositor_is_animating (void)
	Check whether a transition between apps or modals is in progress.
void	compositor_set_modal_transition_offset (GPoint modal_offset)
	Set the offset at which modals are drawn during transitions that redraw them.
void	compositor_transition_cancel (void)
	Stop the current transition, if any; its teardown completes the switch.
void	compositor_freeze (CompositorFrozenCallback callback, void *data)
	Stop new frames from the app or the modal reaching the display.
void	compositor_unfreeze (void)
	Resume pushing frames to the display, undoing compositor_freeze().
void	compositor_scaled_app_fb_copy (const GRect update_rect, bool copy_relative_to_origin)
	Copy part of the app framebuffer into the system framebuffer.
void	compositor_scaled_app_fb_copy_offset (const GRect update_rect, bool copy_relative_to_origin, int16_t offset_y)
	compositor_scaled_app_fb_copy() with a vertical offset applied to the source.
void	compositor_app_framebuffer_fill_callback (GContext *ctx, int16_t y, Fixed_S16_3 x_range_begin, Fixed_S16_3 x_range_end, Fixed_S16_3 delta_begin, Fixed_S16_3 delta_end, void *user_data)
	GPathDrawFilledCallback filling a span with the app framebuffer.

Detailed Description

Composes the app framebuffer and modal windows into the display framebuffer.

The compositor owns the system framebuffer and flushes it to the display. It manages two sources:

• The app framebuffer, which the running app draws into. It is copied (scaled or centered when its size differs from the display) into the system framebuffer whenever the app reports a new frame with compositor_app_render_ready().
• The modal window stack, which is supplied by the kernel and has no framebuffer of its own. It is rendered with the kernel graphics context on top of the app (or alone, when opaque) whenever compositor_modal_render_ready() is called.

Changes between apps or modals can be animated with a CompositorTransition. All functions run on KernelMain unless noted otherwise.

static void prv_init(Animation *animation) {
  animation_set_duration(animation, 6 * ANIMATION_TARGET_FRAME_INTERVAL_MS);
}
 
static void prv_update(GContext *ctx, Animation *animation, uint32_t distance_normalized) {
  // Draw the frame for distance_normalized into ctx, e.g. with compositor_render_app().
}
 
static const CompositorTransition s_my_transition = {
  .init = prv_init,
  .update = prv_update,
};
 
compositor_transition(&s_my_transition);

---

Data Structure Documentation

CompositorTransition

struct CompositorTransition

Implementation of a compositor transition animation.

Data Fields
CompositorTransitionInitFunc	init	Mandatory initialization function.
bool	skip_modal_render_after_update	If false, modals are rendered after each update; if true, they are skipped.
CompositorTransitionTeardownFunc	teardown	Optional teardown function.
CompositorTransitionUpdateFunc	update	Mandatory update function.

Typedef Documentation

CompositorFrozenCallback

typedef void(* CompositorFrozenCallback) (void *data)

Called once the compositor is frozen.

Parameters

data	Data passed to compositor_freeze().

CompositorTransitionInitFunc

typedef void(* CompositorTransitionInitFunc) (Animation *animation)

Set up the transition animation.

Typically sets the duration and curve, and may stash configuration in the animation context.

Parameters

animation

Animation driving the transition.

CompositorTransitionTeardownFunc

typedef void(* CompositorTransitionTeardownFunc) (Animation *animation)

Clean up after a transition finished or was cancelled.

Parameters

animation

Animation driving the transition.

CompositorTransitionUpdateFunc

typedef void(* CompositorTransitionUpdateFunc) (GContext *ctx, Animation *animation, uint32_t distance_normalized)

Draw one frame of a transition.

Parameters

ctx	Kernel graphics context drawing into the system framebuffer. Its draw state is restored after the call.
animation	Animation driving the transition.
distance_normalized	Animation progress, 0 to ANIMATION_NORMALIZED_MAX.

FrameBuffer

typedef struct FrameBuffer FrameBuffer

Opaque framebuffer type, see applib/graphics/framebuffer.h.

Enumeration Type Documentation

CompositorTransitionDirection

enum CompositorTransitionDirection

Transition direction, from the current position to the next.

For example, Up is a transition to an item that lies above the current screen.

Enumerator
CompositorTransitionDirectionUp	Towards the item above.
CompositorTransitionDirectionDown	Towards the item below.
CompositorTransitionDirectionLeft	Towards the item on the left.
CompositorTransitionDirectionRight	Towards the item on the right.
CompositorTransitionDirectionNone	No particular direction.

Function Documentation

compositor_app_framebuffer_fill_callback()

void compositor_app_framebuffer_fill_callback	(	GContext *	ctx,
		int16_t	y,
		Fixed_S16_3	x_range_begin,
		Fixed_S16_3	x_range_end,
		Fixed_S16_3	delta_begin,
		Fixed_S16_3	delta_end,
		void *	user_data
	)

GPathDrawFilledCallback filling a span with the app framebuffer.

Copies the matching pixels of the app framebuffer into the span, for transitions that reveal the app through a path.

Parameters

ctx	Graphics context being drawn into.
y	Row of the span.
x_range_begin	Start of the span.
x_range_end	End of the span.
delta_begin	Unused.
delta_end	Unused.
user_data	Optional const GPoint * offset of the app framebuffer, or NULL.

compositor_app_render_ready()

void compositor_app_render_ready

(

void

)

Notify that the app has a new frame for the display.

Also starts a pending app transition once the app has rendered its first frame. The app framebuffer is released back to the app once copied, or when the transition completes.

compositor_freeze()

void compositor_freeze	(	CompositorFrozenCallback	callback,
		void *	data
	)

Stop new frames from the app or the modal reaching the display.

Callable from any task. callback runs on KernelMain once the freeze is in effect and no display update is in flight, at which point the system framebuffer is stable until compositor_unfreeze(). Only one freeze may be outstanding at a time.

Parameters

callback	Called once frozen.
data	Passed to callback.

compositor_get_app_framebuffer_as_bitmap()

GBitmap compositor_get_app_framebuffer_as_bitmap

(

void

)

Get the app framebuffer as a bitmap.

The bounds are set from app_manager_get_framebuffer_size() rather than the size stored in the app framebuffer, which the app could modify.

Returns

Bitmap covering the app framebuffer.

compositor_get_framebuffer()

FrameBuffer * compositor_get_framebuffer

(

void

)

Get the system framebuffer.

Returns

System framebuffer.

compositor_get_framebuffer_as_bitmap()

GBitmap compositor_get_framebuffer_as_bitmap

(

void

)

Get the system framebuffer as a bitmap.

Returns

Bitmap covering the whole system framebuffer.

compositor_init()

void compositor_init

(

void

)

Initialize the compositor.

Clears the system framebuffer and resets the state to showing the app.

compositor_is_animating()

bool compositor_is_animating

(

void

)

Check whether a transition between apps or modals is in progress.

Returns

true if a transition is running or waiting for the app's first frame.

compositor_modal_render_ready()

void compositor_modal_render_ready

(

void

)

Notify that the modal needs to redraw itself to the display.

Ignored while a transition drives the display or a display update is in progress.

compositor_render_app()

void compositor_render_app

(

void

)

Write the app framebuffer into the system framebuffer.

Clears the system framebuffer to black, copies the app framebuffer (scaled or centered as needed) and renders the modals on top when they are transparent. Must run on KernelMain.

compositor_render_modal()

void compositor_render_modal

(

void

)

Render the modal window stack into the system framebuffer.

Uses the kernel graphics context, offset by the modal transition offset.

compositor_scaled_app_fb_copy()

void compositor_scaled_app_fb_copy	(	const GRect	update_rect,
		bool	copy_relative_to_origin
	)

Copy part of the app framebuffer into the system framebuffer.

The app framebuffer content is scaled or centered in the destination as needed, based on user preference. The region is clipped to the display.

Parameters

update_rect	Region of the system framebuffer to update.
copy_relative_to_origin	If false, the region is filled from the origin of the app framebuffer; if true, from the same region of the app framebuffer.

compositor_scaled_app_fb_copy_offset()

void compositor_scaled_app_fb_copy_offset	(	const GRect	update_rect,
		bool	copy_relative_to_origin,
		int16_t	offset_y
	)

compositor_scaled_app_fb_copy() with a vertical offset applied to the source.

Parameters

update_rect	Region of the system framebuffer to update.
copy_relative_to_origin	See compositor_scaled_app_fb_copy().
offset_y	Vertical offset of the source, in pixels.

compositor_set_modal_transition_offset()

void compositor_set_modal_transition_offset

(

GPoint

modal_offset

)

Set the offset at which modals are drawn during transitions that redraw them.

Parameters

modal_offset

Offset from the display origin.

compositor_transition()

void compositor_transition

(

const CompositorTransition *

impl

)

Start a transition.

A transition already underway is cancelled and replaced by this one. If a display update is in flight or the compositor is frozen, the start is deferred until it can render.

For modal windows, the destination modal must already be on top of the modal window stack. For apps, the destination app must be running, and the animation only begins once it has rendered its first frame.

Parameters

impl	Transition implementation, or NULL to switch without animation.

compositor_transition_cancel()

void compositor_transition_cancel

(

void

)

Stop the current transition, if any; its teardown completes the switch.

compositor_transition_render()

void compositor_transition_render	(	CompositorTransitionUpdateFunc	func,
		Animation *	animation,
		const AnimationProgress	distance_normalized
	)

Render one transition frame with the given update function.

The animation set up by compositor_transition() calls this automatically. Call it from an animation scheduled inside a transition (e.g. one in an animation sequence) so its frames are rendered, deferred and flushed like those of the transition itself.

Parameters

func	Update function drawing the frame.
animation	Animation passed to func.
distance_normalized	Animation progress passed to func.

compositor_unfreeze()

void compositor_unfreeze

(

void

)

Resume pushing frames to the display, undoing compositor_freeze().

Renders deferred while frozen run on KernelMain.