Import of the watch repository from Pebble

src/fw/services/common/compositor/compositor.h

@@ -0,0 +1,135 @@
+/*
+ * Copyright 2024 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#pragma once
+
+#include "applib/ui/property_animation.h"
+#include "applib/ui/window.h"
+
+//! @file kernel/services/compositor.h
+//! This file manages what's currently shown on the screen of your Pebble!
+//! There are two main things that are managed by the compositor...
+//!
+//! <h3>The App Framebuffer</h3>
+//! This is the framebuffer the app is currently drawing into. The compositor
+//! handles animating between app framebuffers when the app changes and window
+//! animations requested by the window stack. The compositor will also draw in
+//! the status bar when the app is in fullscreen, and the app will adjust its
+//! framebuffer's destination frame vertically. The framebuffer is simply
+//! bitblt'ed into the appropriate position whenever compositor_flush is called.
+//!
+//! @see \ref compositor_get_child_entity
+//! @see \ref compositor_set_entity_framebuffer
+//! @see \ref compositor_transition
+//! @see \ref window_stack_animation_schedule
+//! @see \ref app_emit_render_ready_event
+//!
+//! <h3>Modal Window</h3>
+//! A modal window is a Window that can be rendered on top of an app without
+//! interrupting it. The modal window can only be supplied by the kernel, so
+//! we can trust its contents. The modal window is animated up and down the
+//! screen when its pushed and popped. Since the window doesn't have a framebuffer
+//! of its own, we render it to the main framebuffer on top of everything else
+//! whenever compositor_flush is called.
+//!
+
+//! Transition direction, from the current position to the next.
+//! For example, Up is a transition to some item that is upwards of the current screen.
+typedef enum {
+  CompositorTransitionDirectionUp,
+  CompositorTransitionDirectionDown,
+  CompositorTransitionDirectionLeft,
+  CompositorTransitionDirectionRight,
+  CompositorTransitionDirectionNone,
+} CompositorTransitionDirection;
+
+typedef void (*CompositorTransitionInitFunc)(Animation *animation);
+
+// TODO: PBL-31460 Change compositor transitions to use AnimationProgress
+// This would enable time-based bounce back transitions
+typedef void (*CompositorTransitionUpdateFunc)(GContext *ctx, Animation *animation,
+                                              uint32_t distance_normalized);
+
+typedef void (*CompositorTransitionTeardownFunc)(Animation *animation);
+
+typedef struct CompositorTransition {
+  CompositorTransitionInitFunc init;          //!< Mandatory initialization function
+  CompositorTransitionUpdateFunc update;      //!< Mandatory update function
+  CompositorTransitionTeardownFunc teardown;  //!< Optional teardown function
+  //! If false, modals are rendered after the update function, otherwise they are skipped
+  bool skip_modal_render_after_update;
+} CompositorTransition;
+
+typedef struct FrameBuffer FrameBuffer;
+
+void compositor_init(void);
+
+//! Kick off a transition using the given CompositorTransition implementation. If a transition is
+//! already underway the transition will be immediately cancelled and this one will be scheduled
+//! in its place.
+//!
+//! For modal windows the new app we're animating to should already be on top of the modal window
+//! stack. For apps the new app we're animating to should always be running. For apps, the
+//! animation won't begin until the app has already started rendering itself.
+void compositor_transition(const CompositorTransition *impl);
+
+//! Perform the compositor transition rendering steps for a given update function.
+//! Normally you will not call this, as the assigned transition animation automatically runs this.
+//! However, if an animation needs to be scheduled inside of the compositor transition animation,
+//! the new animation will need to call this in order to properly render.
+//! A good use-case for this is when the transition needs to use an animation_sequence.
+//!
+//! For an example of this being used, check out compositor_shutter_transitions.c
+void compositor_transition_render(CompositorTransitionUpdateFunc func, Animation *animation,
+                                  const AnimationProgress distance_normalized);
+
+//! Writes the app framebuffer to either the system framebuffer or display directly.
+//! Calls compositor_render_modal if all modals are transparent as well.
+void compositor_render_app(void);
+
+//! Renders modals using the kernel graphics context
+void compositor_render_modal(void);
+
+//! The modal needs to redraw its buffer to the display.
+void compositor_modal_render_ready(void);
+
+//! The app needs to copy its framebuffer to the display.
+void compositor_app_render_ready(void);
+
+FrameBuffer* compositor_get_framebuffer(void);
+
+GBitmap compositor_get_framebuffer_as_bitmap(void);
+
+//! Gets the app framebuffer as a bitmap. The bounds of the bitmap will be set based on
+//! app_manager_get_framebuffer_size() rather than the app's framebuffer size to protect against
+//! malicious apps changing it.
+GBitmap compositor_get_app_framebuffer_as_bitmap(void);
+
+//! @return True if we're currently mid-animation between apps or modal windows
+bool compositor_is_animating(void);
+
+//! Sets the modal draw offset for transitions that redraw the modal
+void compositor_set_modal_transition_offset(GPoint modal_offset);
+
+//! Stops an existing transition in its tracks.
+void compositor_transition_cancel(void);
+
+//! Don't allow new frames to be pushed to the compostor from either the app or the modal.
+void compositor_freeze(void);
+
+//! Resuming allowing new frames to be pushed to the compositor, undoes the effects of
+//! compositor_freeze.
+void compositor_unfreeze(void);