Native Activity

#include <native_activity.h>
#include <native_window_jni.h>
#include <rect.h>
#include <surface_control.h>
#include <window.h>

Summary

Enumerations
Anonymous Enum 43{
  ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT = 0x0001,
  ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED = 0x0002
} 		enum
Flags for ANativeActivity_showSoftInput; see the Java InputMethodManager API for documentation.
Anonymous Enum 44{
  ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY = 0x0001,
  ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS = 0x0002
} 		enum
Flags for ANativeActivity_hideSoftInput; see the Java InputMethodManager API for documentation.
Anonymous Enum 76{
  ASURFACE_TRANSACTION_VISIBILITY_HIDE = 0,
  ASURFACE_TRANSACTION_VISIBILITY_SHOW = 1
} 		enum
Anonymous Enum 77{
  ASURFACE_TRANSACTION_TRANSPARENCY_TRANSPARENT = 0,
  ASURFACE_TRANSACTION_TRANSPARENCY_TRANSLUCENT = 1,
  ASURFACE_TRANSACTION_TRANSPARENCY_OPAQUE = 2
} 		enum
Anonymous Enum 78{
  AWINDOW_FLAG_ALLOW_LOCK_WHILE_SCREEN_ON = 0x00000001,
  AWINDOW_FLAG_DIM_BEHIND = 0x00000002,
  AWINDOW_FLAG_BLUR_BEHIND = 0x00000004,
  AWINDOW_FLAG_NOT_FOCUSABLE = 0x00000008,
  AWINDOW_FLAG_NOT_TOUCHABLE = 0x00000010,
  AWINDOW_FLAG_NOT_TOUCH_MODAL = 0x00000020,
  AWINDOW_FLAG_TOUCHABLE_WHEN_WAKING = 0x00000040,
  AWINDOW_FLAG_KEEP_SCREEN_ON = 0x00000080,
  AWINDOW_FLAG_LAYOUT_IN_SCREEN = 0x00000100,
  AWINDOW_FLAG_LAYOUT_NO_LIMITS = 0x00000200,
  AWINDOW_FLAG_FULLSCREEN = 0x00000400,
  AWINDOW_FLAG_FORCE_NOT_FULLSCREEN = 0x00000800,
  AWINDOW_FLAG_DITHER = 0x00001000,
  AWINDOW_FLAG_SECURE = 0x00002000,
  AWINDOW_FLAG_SCALED = 0x00004000,
  AWINDOW_FLAG_IGNORE_CHEEK_PRESSES = 0x00008000,
  AWINDOW_FLAG_LAYOUT_INSET_DECOR = 0x00010000,
  AWINDOW_FLAG_ALT_FOCUSABLE_IM = 0x00020000,
  AWINDOW_FLAG_WATCH_OUTSIDE_TOUCH = 0x00040000,
  AWINDOW_FLAG_SHOW_WHEN_LOCKED = 0x00080000,
  AWINDOW_FLAG_SHOW_WALLPAPER = 0x00100000,
  AWINDOW_FLAG_TURN_SCREEN_ON = 0x00200000,
  AWINDOW_FLAG_DISMISS_KEYGUARD = 0x00400000
} 		enum
Window flags, as per the Java API at android.view.WindowManager.LayoutParams.

Typedefs
ANativeActivity typedef
This structure defines the native side of an android.app.NativeActivity.
ANativeActivityCallbacks typedef
These are the callbacks the framework makes into a native application.
ANativeActivity_createFunc(ANativeActivity *activity, void *savedState, size_t savedStateSize) typedef
void
This is the function that must be in the native code to instantiate the application's native activity.
ARect typedef
struct ARect
Rectangular window area.
ASurfaceControl typedef
The SurfaceControl API can be used to provide a hierarchy of surfaces for composition to the system compositor.
ASurfaceTransaction typedef
ASurfaceTransaction is a collection of updates to the surface tree that must be applied atomically.
ASurfaceTransactionStats typedef
An opaque handle returned during a callback that can be used to query general stats and stats for surfaces which were either removed or for which buffers were updated after this transaction was applied.
ASurfaceTransaction_OnComplete)(void *context, ASurfaceTransactionStats *stats) __INTRODUCED_IN(29) typedef
void(*
Since the transactions are applied asynchronously, the ASurfaceTransaction_OnComplete callback can be used to be notified when a frame including the updates in a transaction was presented.

Variables
ANativeActivity_onCreate
The name of the function that NativeInstance looks for when launching its native code.

Functions
ANativeActivity_finish(ANativeActivity *activity)
void
Finish the given activity.
ANativeActivity_hideSoftInput(ANativeActivity *activity, uint32_t flags)
void
Hide the IME while in the given activity.
ANativeActivity_setWindowFlags(ANativeActivity *activity, uint32_t addFlags, uint32_t removeFlags)
void
Change the window flags of the given activity.
ANativeActivity_setWindowFormat(ANativeActivity *activity, int32_t format)
void
Change the window format of the given activity.
ANativeActivity_showSoftInput(ANativeActivity *activity, uint32_t flags)
void
Show the IME while in the given activity.
ANativeWindow_fromSurface(JNIEnv *env, jobject surface)
Return the ANativeWindow associated with a Java Surface object, for interacting with it through native code.
ANativeWindow_toSurface(JNIEnv *env, ANativeWindow *window)
jobject
Return a Java Surface object derived from the ANativeWindow, for interacting with it through Java code.
ASurfaceControl_create(ASurfaceControl *parent, const char *debug_name)
ASurfaceControl_createFromWindow(ANativeWindow *parent, const char *debug_name)
ASurfaceControl_release(ASurfaceControl *surface_control)
void
Releases the |surface_control| object.
ASurfaceTransactionStats_getASurfaceControls(ASurfaceTransactionStats *surface_transaction_stats, ASurfaceControl ***outASurfaceControls, size_t *outASurfaceControlsSize)
void
|outASurfaceControls| returns an array of ASurfaceControl pointers that were updated during the transaction.
ASurfaceTransactionStats_getAcquireTime(ASurfaceTransactionStats *surface_transaction_stats, ASurfaceControl *surface_control)
int64_t
Returns the timestamp of when the CURRENT buffer was acquired.
ASurfaceTransactionStats_getLatchTime(ASurfaceTransactionStats *surface_transaction_stats)
int64_t
Returns the timestamp of when the frame was latched by the framework.
ASurfaceTransactionStats_getPresentFenceFd(ASurfaceTransactionStats *surface_transaction_stats)
int
Returns a sync fence that signals when the transaction has been presented.
ASurfaceTransactionStats_getPreviousReleaseFenceFd(ASurfaceTransactionStats *surface_transaction_stats, ASurfaceControl *surface_control)
int
The returns the fence used to signal the release of the PREVIOUS buffer set on this surface.
ASurfaceTransactionStats_releaseASurfaceControls(ASurfaceControl **surface_controls)
void
Releases the array of ASurfaceControls that were returned by ASurfaceTransactionStats_getASurfaceControls.
ASurfaceTransaction_apply(ASurfaceTransaction *transaction)
void
Applies the updates accumulated in |transaction|.
ASurfaceTransaction_create()
The caller takes ownership of the transaction and must release it using ASurfaceControl_delete below.
ASurfaceTransaction_delete(ASurfaceTransaction *transaction)
void
Destroys the |transaction| object.
ASurfaceTransaction_reparent(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, ASurfaceControl *new_parent)
void
Reparents the |surface_control| from its old parent to the |new_parent| surface control.
ASurfaceTransaction_setBuffer(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, AHardwareBuffer *buffer, int acquire_fence_fd)
void
Updates the AHardwareBuffer displayed for |surface_control|.
ASurfaceTransaction_setBufferAlpha(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, float alpha)
void
Sets the alpha for the buffer.
ASurfaceTransaction_setBufferDataSpace(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, ADataSpace data_space)
void
Sets the data space of the surface_control's buffers.
ASurfaceTransaction_setBufferTransparency(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, int8_t transparency)
void
Updates whether the content for the buffer associated with this surface is completely opaque.
ASurfaceTransaction_setColor(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, float r, float g, float b, float alpha, ADataSpace dataspace)
void
Updates the color for |surface_control|.
ASurfaceTransaction_setDamageRegion(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, const ARect rects[], uint32_t count)
void
Updates the region for the content on this surface updated in this transaction.
ASurfaceTransaction_setDesiredPresentTime(ASurfaceTransaction *transaction, int64_t desiredPresentTime)
void
Specifies a desiredPresentTime for the transaction.
ASurfaceTransaction_setGeometry(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, const ARect & source, const ARect & destination, int32_t transform)
void
|source| the sub-rect within the buffer's content to be rendered inside the surface's area The surface's source rect is clipped by the bounds of its current buffer.
ASurfaceTransaction_setHdrMetadata_cta861_3(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, struct AHdrMetadata_cta861_3 *metadata)
void
ASurfaceTransaction_setHdrMetadata_smpte2086(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, struct AHdrMetadata_smpte2086 *metadata)
void
ASurfaceTransaction_setOnComplete(ASurfaceTransaction *transaction, void *context, ASurfaceTransaction_OnComplete func)
void
Sets the callback that will be invoked when the updates from this transaction are presented.
ASurfaceTransaction_setVisibility(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, int8_t visibility)
void
Updates the visibility of |surface_control|.
ASurfaceTransaction_setZOrder(ASurfaceTransaction *transaction, ASurfaceControl *surface_control, int32_t z_order)
void
Updates the z order index for |surface_control|.

Structs
ANativeActivity

This structure defines the native side of an android.app.NativeActivity.

ANativeActivityCallbacks

These are the callbacks the framework makes into a native application.

ARect

Rectangular window area.

Enumerations

Anonymous Enum 43

 Anonymous Enum 43

Flags for ANativeActivity_showSoftInput; see the Java InputMethodManager API for documentation.

Properties
ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED

The user has forced the input method open (such as by long-pressing menu) so it should not be closed until they explicitly do so.

ANATIVEACTIVITY_SHOW_SOFT_INPUT_IMPLICIT

Implicit request to show the input window, not as the result of a direct request by the user.

Anonymous Enum 44

 Anonymous Enum 44

Flags for ANativeActivity_hideSoftInput; see the Java InputMethodManager API for documentation.

Properties
ANATIVEACTIVITY_HIDE_SOFT_INPUT_IMPLICIT_ONLY

The soft input window should only be hidden if it was not explicitly shown by the user.

ANATIVEACTIVITY_HIDE_SOFT_INPUT_NOT_ALWAYS

The soft input window should normally be hidden, unless it was originally shown with ANATIVEACTIVITY_SHOW_SOFT_INPUT_FORCED.

Anonymous Enum 76

 Anonymous Enum 76

Anonymous Enum 77

 Anonymous Enum 77

Anonymous Enum 78

 Anonymous Enum 78

Window flags, as per the Java API at android.view.WindowManager.LayoutParams.

Properties
AWINDOW_FLAG_ALLOW_LOCK_WHILE_SCREEN_ON

As long as this window is visible to the user, allow the lock screen to activate while the screen is on.

This can be used independently, or in combination with AWINDOW_FLAG_KEEP_SCREEN_ON and/or AWINDOW_FLAG_SHOW_WHEN_LOCKED
AWINDOW_FLAG_ALT_FOCUSABLE_IM

Invert the state of AWINDOW_FLAG_NOT_FOCUSABLE with respect to how this window interacts with the current method.

That is, if FLAG_NOT_FOCUSABLE is set and this flag is set, then the window will behave as if it needs to interact with the input method and thus be placed behind/away from it; if AWINDOW_FLAG_NOT_FOCUSABLE is not set and this flag is set, then the window will behave as if it doesn't need to interact with the input method and can be placed to use more space and cover the input method.

AWINDOW_FLAG_BLUR_BEHIND

Blur everything behind this window.

Deprecated. Blurring is no longer supported.

AWINDOW_FLAG_DIM_BEHIND

Everything behind this window will be dimmed.

AWINDOW_FLAG_DISMISS_KEYGUARD

When set the window will cause the keyguard to be dismissed, only if it is not a secure lock keyguard.

Because such a keyguard is not needed for security, it will never re-appear if the user navigates to another window (in contrast to AWINDOW_FLAG_SHOW_WHEN_LOCKED, which will only temporarily hide both secure and non-secure keyguards but ensure they reappear when the user moves to another UI that doesn't hide them). If the keyguard is currently active and is secure (requires an unlock pattern) than the user will still need to confirm it before seeing this window, unless AWINDOW_FLAG_SHOW_WHEN_LOCKED has also been set.

AWINDOW_FLAG_DITHER

Turn on dithering when compositing this window to the screen.

Deprecated. This flag is no longer used.

AWINDOW_FLAG_FORCE_NOT_FULLSCREEN

Override AWINDOW_FLAG_FULLSCREEN and force the screen decorations (such as the status bar) to be shown.

AWINDOW_FLAG_FULLSCREEN

Hide all screen decorations (such as the status bar) while this window is displayed.

This allows the window to use the entire display space for itself the status bar will be hidden when an app window with this flag set is on the top layer. A fullscreen window will ignore a value of AWINDOW_SOFT_INPUT_ADJUST_RESIZE; the window will stay fullscreen and will not resize.

AWINDOW_FLAG_IGNORE_CHEEK_PRESSES

Intended for windows that will often be used when the user is holding the screen against their face, it will aggressively filter the event stream to prevent unintended presses in this situation that may not be desired for a particular window, when such an event stream is detected, the application will receive a AMOTION_EVENT_ACTION_CANCEL to indicate this so applications can handle this accordingly by taking no action on the event until the finger is released.

AWINDOW_FLAG_KEEP_SCREEN_ON

As long as this window is visible to the user, keep the device's screen turned on and bright.

AWINDOW_FLAG_LAYOUT_INSET_DECOR

A special option only for use in combination with AWINDOW_FLAG_LAYOUT_IN_SCREEN.

When requesting layout in the screen your window may appear on top of or behind screen decorations such as the status bar. By also including this flag, the window manager will report the inset rectangle needed to ensure your content is not covered by screen decorations.

AWINDOW_FLAG_LAYOUT_IN_SCREEN

Place the window within the entire screen, ignoring decorations around the border (such as the status bar).

The window must correctly position its contents to take the screen decoration into account.

AWINDOW_FLAG_LAYOUT_NO_LIMITS

allow window to extend outside of the screen.

AWINDOW_FLAG_NOT_FOCUSABLE

This window won't ever get key input focus, so the user can not send key or other button events to it.

Those will instead go to whatever focusable window is behind it. This flag will also enable AWINDOW_FLAG_NOT_TOUCH_MODAL whether or not that is explicitly set.

Setting this flag also implies that the window will not need to interact with a soft input method, so it will be Z-ordered and positioned independently of any active input method (typically this means it gets Z-ordered on top of the input method, so it can use the full screen for its content and cover the input method if needed. You can use AWINDOW_FLAG_ALT_FOCUSABLE_IM to modify this behavior.

AWINDOW_FLAG_NOT_TOUCHABLE

this window can never receive touch events.

AWINDOW_FLAG_NOT_TOUCH_MODAL

Even when this window is focusable (its AWINDOW_FLAG_NOT_FOCUSABLE is not set), allow any pointer events outside of the window to be sent to the windows behind it.

Otherwise it will consume all pointer events itself, regardless of whether they are inside of the window.

AWINDOW_FLAG_SCALED

A special mode where the layout parameters are used to perform scaling of the surface when it is composited to the screen.

AWINDOW_FLAG_SECURE

Treat the content of the window as secure, preventing it from appearing in screenshots or from being viewed on non-secure displays.

AWINDOW_FLAG_SHOW_WALLPAPER

Ask that the system wallpaper be shown behind your window.

The window surface must be translucent to be able to actually see the wallpaper behind it; this flag just ensures that the wallpaper surface will be there if this window actually has translucent regions.

AWINDOW_FLAG_SHOW_WHEN_LOCKED

Special flag to let windows be shown when the screen is locked.

This will let application windows take precedence over key guard or any other lock screens. Can be used with AWINDOW_FLAG_KEEP_SCREEN_ON to turn screen on and display windows directly before showing the key guard window. Can be used with AWINDOW_FLAG_DISMISS_KEYGUARD to automatically fully dismisss non-secure keyguards. This flag only applies to the top-most full-screen window.

AWINDOW_FLAG_TOUCHABLE_WHEN_WAKING

When set, if the device is asleep when the touch screen is pressed, you will receive this first touch event.

Usually the first touch event is consumed by the system since the user can not see what they are pressing on.

Deprecated. This flag has no effect.

AWINDOW_FLAG_TURN_SCREEN_ON

When set as a window is being added or made visible, once the window has been shown then the system will poke the power manager's user activity (as if the user had woken up the device) to turn the screen on.

AWINDOW_FLAG_WATCH_OUTSIDE_TOUCH

If you have set AWINDOW_FLAG_NOT_TOUCH_MODAL, you can set this flag to receive a single special MotionEvent with the action AMOTION_EVENT_ACTION_OUTSIDE for touches that occur outside of your window.

Note that you will not receive the full down/move/up gesture, only the location of the first down as an AMOTION_EVENT_ACTION_OUTSIDE.

Typedefs

ANativeActivity

struct ANativeActivity ANativeActivity

This structure defines the native side of an android.app.NativeActivity.

It is created by the framework, and handed to the application's native code as it is being launched.

ANativeActivityCallbacks

struct ANativeActivityCallbacks ANativeActivityCallbacks

These are the callbacks the framework makes into a native application.

All of these callbacks happen on the main thread of the application. By default, all callbacks are NULL; set to a pointer to your own function to have it called.

ANativeActivity_createFunc

void ANativeActivity_createFunc(ANativeActivity *activity, void *savedState, size_t savedStateSize)

This is the function that must be in the native code to instantiate the application's native activity.

It is called with the activity instance (see above); if the code is being instantiated from a previously saved instance, the savedState will be non-NULL and point to the saved data. You must make any copy of this data you need it will be released after you return from this function.

ARect

struct ARect ARect

Rectangular window area.

This is the NDK equivalent of the android.graphics.Rect class in Java. It is used with ANativeActivityCallbacks::onContentRectChanged event callback and the ANativeWindow_lock() function.

In a valid ARect, left <= right and top <= bottom. ARect with left=0, top=10, right=1, bottom=11 contains only one pixel at x=0, y=10.

ASurfaceControl

struct ASurfaceControl ASurfaceControl

The SurfaceControl API can be used to provide a hierarchy of surfaces for composition to the system compositor.

ASurfaceControl represents a content node in this hierarchy.

ASurfaceTransaction

struct ASurfaceTransaction ASurfaceTransaction

ASurfaceTransaction is a collection of updates to the surface tree that must be applied atomically.

ASurfaceTransactionStats

struct ASurfaceTransactionStats ASurfaceTransactionStats

An opaque handle returned during a callback that can be used to query general stats and stats for surfaces which were either removed or for which buffers were updated after this transaction was applied.

ASurfaceTransaction_OnComplete

void(* ASurfaceTransaction_OnComplete)(void *context, ASurfaceTransactionStats *stats) __INTRODUCED_IN(29)

Since the transactions are applied asynchronously, the ASurfaceTransaction_OnComplete callback can be used to be notified when a frame including the updates in a transaction was presented.

|context| is the optional context provided by the client that is passed into the callback.

|stats| is an opaque handle that can be passed to ASurfaceTransactionStats functions to query information about the transaction. The handle is only valid during the callback.

THREADING The transaction completed callback can be invoked on any thread.

Variables

ANativeActivity_onCreate

ANativeActivity_createFunc ANativeActivity_onCreate

The name of the function that NativeInstance looks for when launching its native code.

This is the default function that is used, you can specify "android.app.func_name" string meta-data in your manifest to use a different function.

Functions

ANativeActivity_finish

void ANativeActivity_finish(
  ANativeActivity *activity
)

Finish the given activity.

Its finish() method will be called, causing it to be stopped and destroyed. Note that this method can be called from any thread; it will send a message to the main thread of the process where the Java finish call will take place.

ANativeActivity_hideSoftInput

void ANativeActivity_hideSoftInput(
  ANativeActivity *activity,
  uint32_t flags
)

Hide the IME while in the given activity.

Calls InputMethodManager.hideSoftInput() for the given activity. Note that this method can be called from any thread; it will send a message to the main thread of the process where the Java finish call will take place.

ANativeActivity_setWindowFlags

void ANativeActivity_setWindowFlags(
  ANativeActivity *activity,
  uint32_t addFlags,
  uint32_t removeFlags
)

Change the window flags of the given activity.

Calls getWindow().setFlags() of the given activity. Note that this method can be called from any thread; it will send a message to the main thread of the process where the Java finish call will take place. See window.h for flag constants.

ANativeActivity_setWindowFormat

void ANativeActivity_setWindowFormat(
  ANativeActivity *activity,
  int32_t format
)

Change the window format of the given activity.

Calls getWindow().setFormat() of the given activity. Note that this method can be called from any thread; it will send a message to the main thread of the process where the Java finish call will take place.

ANativeActivity_showSoftInput

void ANativeActivity_showSoftInput(
  ANativeActivity *activity,
  uint32_t flags
)

Show the IME while in the given activity.

Calls InputMethodManager.showSoftInput() for the given activity. Note that this method can be called from any thread; it will send a message to the main thread of the process where the Java finish call will take place.

ANativeWindow_fromSurface

ANativeWindow * ANativeWindow_fromSurface(
  JNIEnv *env,
  jobject surface
)

Return the ANativeWindow associated with a Java Surface object, for interacting with it through native code.

This acquires a reference on the ANativeWindow that is returned; be sure to use ANativeWindow_release() when done with it so that it doesn't leak.

ANativeWindow_toSurface

jobject ANativeWindow_toSurface(
  JNIEnv *env,
  ANativeWindow *window
)

Return a Java Surface object derived from the ANativeWindow, for interacting with it through Java code.

The returned Java object acquires a reference on the ANativeWindow; maintains it through general Java object's life cycle; and will automatically release the reference when the Java object gets garbage collected.

ASurfaceControl_create

ASurfaceControl * ASurfaceControl_create(
  ASurfaceControl *parent,
  const char *debug_name
)

ASurfaceControl_createFromWindow

ASurfaceControl * ASurfaceControl_createFromWindow(
  ANativeWindow *parent,
  const char *debug_name
)

ASurfaceControl_release

void ASurfaceControl_release(
  ASurfaceControl *surface_control
)

Releases the |surface_control| object.

After releasing the ASurfaceControl the caller no longer has ownership of the AsurfaceControl. The surface and it's children may remain on display as long as their parent remains on display.

ASurfaceTransactionStats_getASurfaceControls

void ASurfaceTransactionStats_getASurfaceControls(
  ASurfaceTransactionStats *surface_transaction_stats,
  ASurfaceControl ***outASurfaceControls,
  size_t *outASurfaceControlsSize
)

|outASurfaceControls| returns an array of ASurfaceControl pointers that were updated during the transaction.

Stats for the surfaces can be queried through ASurfaceTransactionStats functions. When the client is done using the array, it must release it by calling ASurfaceTransactionStats_releaseASurfaceControls.

|outASurfaceControlsSize| returns the size of the ASurfaceControls array.

ASurfaceTransactionStats_getAcquireTime

int64_t ASurfaceTransactionStats_getAcquireTime(
  ASurfaceTransactionStats *surface_transaction_stats,
  ASurfaceControl *surface_control
)

Returns the timestamp of when the CURRENT buffer was acquired.

A buffer is considered acquired when its acquire_fence_fd has signaled. A buffer cannot be latched or presented until it is acquired. If no acquire_fence_fd was provided, this timestamp will be set to -1.

ASurfaceTransactionStats_getLatchTime

int64_t ASurfaceTransactionStats_getLatchTime(
  ASurfaceTransactionStats *surface_transaction_stats
)

Returns the timestamp of when the frame was latched by the framework.

Once a frame is latched by the framework, it is presented at the following hardware vsync.

ASurfaceTransactionStats_getPresentFenceFd

int ASurfaceTransactionStats_getPresentFenceFd(
  ASurfaceTransactionStats *surface_transaction_stats
)

Returns a sync fence that signals when the transaction has been presented.

The recipient of the callback takes ownership of the fence and is responsible for closing it.

ASurfaceTransactionStats_getPreviousReleaseFenceFd

int ASurfaceTransactionStats_getPreviousReleaseFenceFd(
  ASurfaceTransactionStats *surface_transaction_stats,
  ASurfaceControl *surface_control
)

The returns the fence used to signal the release of the PREVIOUS buffer set on this surface.

If this fence is valid (>=0), the PREVIOUS buffer has not yet been released and the fence will signal when the PREVIOUS buffer has been released. If the fence is -1 , the PREVIOUS buffer is already released. The recipient of the callback takes ownership of the previousReleaseFenceFd and is responsible for closing it.

Each time a buffer is set through ASurfaceTransaction_setBuffer()/_setCachedBuffer() on a transaction which is applied, the framework takes a ref on this buffer. The framework treats the addition of a buffer to a particular surface as a unique ref. When a transaction updates or removes a buffer from a surface, or removes the surface itself from the tree, this ref is guaranteed to be released in the OnComplete callback for this transaction. The ASurfaceControlStats provided in the callback for this surface may contain an optional fence which must be signaled before the ref is assumed to be released.

The client must ensure that all pending refs on a buffer are released before attempting to reuse this buffer, otherwise synchronization errors may occur.

ASurfaceTransactionStats_releaseASurfaceControls

void ASurfaceTransactionStats_releaseASurfaceControls(
  ASurfaceControl **surface_controls
)

Releases the array of ASurfaceControls that were returned by ASurfaceTransactionStats_getASurfaceControls.

ASurfaceTransaction_apply

void ASurfaceTransaction_apply(
  ASurfaceTransaction *transaction
)

Applies the updates accumulated in |transaction|.

Note that the transaction is guaranteed to be applied atomically. The transactions which are applied on the same thread are also guaranteed to be applied in order.

ASurfaceTransaction_create

ASurfaceTransaction * ASurfaceTransaction_create()

The caller takes ownership of the transaction and must release it using ASurfaceControl_delete below.

ASurfaceTransaction_delete

void ASurfaceTransaction_delete(
  ASurfaceTransaction *transaction
)

Destroys the |transaction| object.

ASurfaceTransaction_reparent

void ASurfaceTransaction_reparent(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  ASurfaceControl *new_parent
)

Reparents the |surface_control| from its old parent to the |new_parent| surface control.

Any children of the* reparented |surface_control| will remain children of the |surface_control|.

The |new_parent| can be null. Surface controls with a null parent do not appear on the display.

ASurfaceTransaction_setBuffer

void ASurfaceTransaction_setBuffer(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  AHardwareBuffer *buffer,
  int acquire_fence_fd
)

Updates the AHardwareBuffer displayed for |surface_control|.

If not -1, the acquire_fence_fd should be a file descriptor that is signaled when all pending work for the buffer is complete and the buffer can be safely read.

The frameworks takes ownership of the |acquire_fence_fd| passed and is responsible for closing it.

ASurfaceTransaction_setBufferAlpha

void ASurfaceTransaction_setBufferAlpha(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  float alpha
)

Sets the alpha for the buffer.

It uses a premultiplied blending.

The |alpha| must be between 0.0 and 1.0.

ASurfaceTransaction_setBufferDataSpace

void ASurfaceTransaction_setBufferDataSpace(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  ADataSpace data_space
)

Sets the data space of the surface_control's buffers.

If no data space is set, the surface control defaults to ADATASPACE_SRGB.

ASurfaceTransaction_setBufferTransparency

void ASurfaceTransaction_setBufferTransparency(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  int8_t transparency
)

Updates whether the content for the buffer associated with this surface is completely opaque.

If true, every pixel of content inside the buffer must be opaque or visual errors can occur.

ASurfaceTransaction_setColor

void ASurfaceTransaction_setColor(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  float r,
  float g,
  float b,
  float alpha,
  ADataSpace dataspace
)

Updates the color for |surface_control|.

This will make the background color for the ASurfaceControl visible in transparent regions of the surface. Colors |r|, |g|, and |b| must be within the range that is valid for |dataspace|. |dataspace| and |alpha| will be the dataspace and alpha set for the background color layer.

ASurfaceTransaction_setDamageRegion

void ASurfaceTransaction_setDamageRegion(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  const ARect rects[],
  uint32_t count
)

Updates the region for the content on this surface updated in this transaction.

If unspecified, the complete surface is assumed to be damaged.

ASurfaceTransaction_setDesiredPresentTime

void ASurfaceTransaction_setDesiredPresentTime(
  ASurfaceTransaction *transaction,
  int64_t desiredPresentTime
)

Specifies a desiredPresentTime for the transaction.

The framework will try to present the transaction at or after the time specified.

Transactions will not be presented until all of their acquire fences have signaled even if the app requests an earlier present time.

If an earlier transaction has a desired present time of x, and a later transaction has a desired present time that is before x, the later transaction will not preempt the earlier transaction.

ASurfaceTransaction_setGeometry

void ASurfaceTransaction_setGeometry(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  const ARect & source,
  const ARect & destination,
  int32_t transform
)

|source| the sub-rect within the buffer's content to be rendered inside the surface's area The surface's source rect is clipped by the bounds of its current buffer.

The source rect's width and height must be > 0.

|destination| specifies the rect in the parent's space where this surface will be drawn. The post source rect bounds are scaled to fit the destination rect. The surface's destination rect is clipped by the bounds of its parent. The destination rect's width and height must be > 0.

|transform| the transform applied after the source rect is applied to the buffer. This parameter should be set to 0 for no transform. To specify a transfrom use the NATIVE_WINDOW_TRANSFORM_* enum.

ASurfaceTransaction_setHdrMetadata_cta861_3

void ASurfaceTransaction_setHdrMetadata_cta861_3(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  struct AHdrMetadata_cta861_3 *metadata
)

ASurfaceTransaction_setHdrMetadata_smpte2086

void ASurfaceTransaction_setHdrMetadata_smpte2086(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  struct AHdrMetadata_smpte2086 *metadata
)

ASurfaceTransaction_setOnComplete

void ASurfaceTransaction_setOnComplete(
  ASurfaceTransaction *transaction,
  void *context,
  ASurfaceTransaction_OnComplete func
)

Sets the callback that will be invoked when the updates from this transaction are presented.

For details on the callback semantics and data, see the comments on the ASurfaceTransaction_OnComplete declaration above.

ASurfaceTransaction_setVisibility

void ASurfaceTransaction_setVisibility(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  int8_t visibility
)

Updates the visibility of |surface_control|.

If show is set to ASURFACE_TRANSACTION_VISIBILITY_HIDE, the |surface_control| and all surfaces in its subtree will be hidden.

ASurfaceTransaction_setZOrder

void ASurfaceTransaction_setZOrder(
  ASurfaceTransaction *transaction,
  ASurfaceControl *surface_control,
  int32_t z_order
)

Updates the z order index for |surface_control|.

Note that the z order for a surface is relative to other surfaces which are siblings of this surface. The behavior of sibilings with the same z order is undefined.

Z orders may be from MIN_INT32 to MAX_INT32. A layer's default z order index is 0.