Native Activity

#include <native_activity.h>

#include <native_window_jni.h>

#include <rect.h>

#include <surface_control.h>

#include <surface_control_jni.h>

#include <window.h>

Summary

Enumerations
Anonymous Enum 107{ 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.
`Anonymous Enum 51{ 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 52{ 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.
`ASurfaceTransactionTransparency{ ASURFACE_TRANSACTION_TRANSPARENCY_TRANSPARENT = 0, ASURFACE_TRANSACTION_TRANSPARENCY_TRANSLUCENT = 1, ASURFACE_TRANSACTION_TRANSPARENCY_OPAQUE = 2 }`	enum Parameter for ASurfaceTransaction_setBufferTransparency().
`ASurfaceTransactionVisibility{ ASURFACE_TRANSACTION_VISIBILITY_HIDE = 0, ASURFACE_TRANSACTION_VISIBILITY_SHOW = 1 }`	enum Parameter for ASurfaceTransaction_setVisibility().

Typedefs
`ANativeActivity`	typedef `struct ANativeActivity` This structure defines the native side of an android.app.NativeActivity.
`ANativeActivityCallbacks`	typedef `struct ANativeActivityCallbacks` 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 `struct ASurfaceControl` The SurfaceControl API can be used to provide a hierarchy of surfaces for composition to the system compositor.
`ASurfaceTransaction`	typedef `struct ASurfaceTransaction` ASurfaceTransaction is a collection of updates to the surface tree that must be applied atomically.
`ASurfaceTransactionStats`	typedef `struct 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_OnCommit)(void _Null_unspecified context, ASurfaceTransactionStats _Nonnull stats)`	typedef `void(*` The ASurfaceTransaction_OnCommit callback is invoked when transaction is applied and the updates are ready to be presented.
`ASurfaceTransaction_OnComplete)(void _Null_unspecified context, ASurfaceTransactionStats _Nonnull stats)`	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`	`ANativeActivity_createFunc` 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)`	`ANativeWindow *` 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_acquire(ASurfaceControl *_Nonnull surface_control)`	`void` Acquires a reference on the given ASurfaceControl object.
`ASurfaceControl_create(ASurfaceControl _Nonnull parent, const char _Nonnull debug_name)`	`ASurfaceControl *_Nullable` See ASurfaceControl_createFromWindow.
`ASurfaceControl_createFromWindow(ANativeWindow _Nonnull parent, const char _Nonnull debug_name)`	`ASurfaceControl *_Nullable` Creates an ASurfaceControl with either ANativeWindow or an ASurfaceControl as its parent.
`ASurfaceControl_fromJava(JNIEnv *_Nonnull env, jobject _Nonnull surfaceControlObj)`	`ASurfaceControl *_Nonnull` Return the ASurfaceControl wrapped by a Java SurfaceControl object.
`ASurfaceControl_release(ASurfaceControl *_Nonnull surface_control)`	`void` Removes a reference that was previously acquired with one of the following functions: ASurfaceControl_createFromWindow ASurfaceControl_create ANativeWindow_acquire The surface and its children may remain on display as long as their parent remains on display.
`ASurfaceTransactionStats_getASurfaceControls(ASurfaceTransactionStats _Nonnull surface_transaction_stats, ASurfaceControl _Nullable _Nullable _Nonnull outASurfaceControls, size_t *_Nonnull outASurfaceControlsSize)`	`void` outASurfaceControls returns an array of ASurfaceControl pointers that were updated during the transaction.
`ASurfaceTransactionStats_getAcquireTime(ASurfaceTransactionStats _Nonnull surface_transaction_stats, ASurfaceControl _Nonnull surface_control)`	`int64_t` Returns the timestamp of when the CURRENT buffer was acquired.
`ASurfaceTransactionStats_getLatchTime(ASurfaceTransactionStats *_Nonnull surface_transaction_stats)`	`int64_t` Returns the timestamp of when the frame was latched by the framework.
`ASurfaceTransactionStats_getPresentFenceFd(ASurfaceTransactionStats *_Nonnull surface_transaction_stats)`	`int` Returns a sync fence that signals when the transaction has been presented.
`ASurfaceTransactionStats_getPreviousReleaseFenceFd(ASurfaceTransactionStats _Nonnull surface_transaction_stats, ASurfaceControl _Nonnull surface_control)`	`int` The returns the fence used to signal the release of the PREVIOUS buffer set on this surface.
`ASurfaceTransactionStats_releaseASurfaceControls(ASurfaceControl _Nonnull _Nonnull surface_controls)`	`void` Releases the array of ASurfaceControls that were returned by ASurfaceTransactionStats_getASurfaceControls().
`ASurfaceTransaction_apply(ASurfaceTransaction *_Nonnull transaction)`	`void` Applies the updates accumulated in transaction.
`ASurfaceTransaction_clearFrameRate(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control)`	`void` Clears the frame rate which is set for surface_control.
`ASurfaceTransaction_create()`	`ASurfaceTransaction *_Nonnull` The caller takes ownership of the transaction and must release it using ASurfaceTransaction_delete() below.
`ASurfaceTransaction_delete(ASurfaceTransaction *_Nullable transaction)`	`void` Destroys the transaction object.
`ASurfaceTransaction_fromJava(JNIEnv *_Nonnull env, jobject _Nonnull transactionObj)`	`ASurfaceTransaction *_Nonnull` Return the ASurfaceTransaction wrapped by a Java Transaction object.
`ASurfaceTransaction_reparent(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, ASurfaceControl *_Nullable new_parent)`	`void` Reparents the surface_control from its old parent to the new_parent surface control.
`ASurfaceTransaction_setBuffer(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, AHardwareBuffer *_Nonnull buffer, int acquire_fence_fd)`	`void` Updates the AHardwareBuffer displayed for surface_control.
`ASurfaceTransaction_setBufferAlpha(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, float alpha)`	`void` Sets the alpha for the buffer.
`ASurfaceTransaction_setBufferDataSpace(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, enum ADataSpace data_space)`	`void` Sets the data space of the surface_control's buffers.
`ASurfaceTransaction_setBufferTransform(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, int32_t transform)`	`void`
`ASurfaceTransaction_setBufferTransparency(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, enum ASurfaceTransactionTransparency transparency)`	`void` Updates whether the content for the buffer associated with this surface is completely opaque.
`ASurfaceTransaction_setColor(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, float r, float g, float b, float alpha, enum ADataSpace dataspace)`	`void` Updates the color for surface_control.
`ASurfaceTransaction_setCrop(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, const ARect *_Nonnull crop)`	`void` Bounds the surface and its children to the bounds specified.
`ASurfaceTransaction_setDamageRegion(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, const ARect *_Nullable rects, uint32_t count)`	`void` Updates the region for the content on this surface updated in this transaction.
`ASurfaceTransaction_setDesiredHdrHeadroom(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, float desiredHeadroom)`	`void` Sets the desired hdr headroom for the layer.
`ASurfaceTransaction_setDesiredPresentTime(ASurfaceTransaction *_Nonnull transaction, int64_t desiredPresentTime)`	`void` Specifies a desiredPresentTime for the transaction.
`ASurfaceTransaction_setEnableBackPressure(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, bool enableBackPressure)`	`void` Indicate whether to enable backpressure for buffer submission to a given SurfaceControl.
`ASurfaceTransaction_setExtendedRangeBrightness(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, float currentBufferRatio, float desiredRatio)`	`void` Sets the desired extended range brightness for the layer.
`ASurfaceTransaction_setFrameRate(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, float frameRate, int8_t compatibility)`	`void` Same as ASurfaceTransaction_setFrameRateWithChangeStrategy(transaction, surface_control, frameRate, compatibility, ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS).
`ASurfaceTransaction_setFrameRateWithChangeStrategy(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, float frameRate, int8_t compatibility, int8_t changeFrameRateStrategy)`	`void` Sets the intended frame rate for surface_control.
`ASurfaceTransaction_setFrameTimeline(ASurfaceTransaction *_Nonnull transaction, AVsyncId vsyncId)`	`void` Sets the frame timeline to use in SurfaceFlinger.
`ASurfaceTransaction_setGeometry(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, const ARect _Nonnull source, const ARect _Nonnull destination, int32_t transform)`	`void` Deprecated. Use setCrop, setPosition, setBufferTransform, and setScale instead. Those functions provide well defined behavior and allows for more control by the apps. It also allows the caller to set different properties at different times, instead of having to specify all the desired properties at once.
`ASurfaceTransaction_setHdrMetadata_cta861_3(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, struct AHdrMetadata_cta861_3 *_Nullable metadata)`	`void` Sets the CTA 861.3 "HDR Static Metadata Extension" static metadata on a surface.
`ASurfaceTransaction_setHdrMetadata_smpte2086(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, struct AHdrMetadata_smpte2086 *_Nullable metadata)`	`void` SMPTE ST 2086 "Mastering Display Color Volume" static metadata.
`ASurfaceTransaction_setOnCommit(ASurfaceTransaction _Nonnull transaction, void _Null_unspecified context, ASurfaceTransaction_OnCommit _Nonnull func)`	`void` Sets the callback that will be invoked when the updates from this transaction are applied and are ready to be presented.
`ASurfaceTransaction_setOnComplete(ASurfaceTransaction _Nonnull transaction, void _Null_unspecified context, ASurfaceTransaction_OnComplete _Nonnull func)`	`void` Sets the callback that will be invoked when the updates from this transaction are presented.
`ASurfaceTransaction_setPosition(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, int32_t x, int32_t y)`	`void` Specifies the position in the parent's space where the surface will be drawn.
`ASurfaceTransaction_setScale(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, float xScale, float yScale)`	`void` Sets an x and y scale of a surface with (0, 0) as the centerpoint of the scale.
`ASurfaceTransaction_setVisibility(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull surface_control, enum ASurfaceTransactionVisibility visibility)`	`void` Updates the visibility of surface_control.
`ASurfaceTransaction_setZOrder(ASurfaceTransaction _Nonnull transaction, ASurfaceControl _Nonnull 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 107

 Anonymous Enum 107

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

Anonymous Enum 51

 Anonymous Enum 51

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 52

 Anonymous Enum 52

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.

ASurfaceTransactionTransparency

 ASurfaceTransactionTransparency

Parameter for ASurfaceTransaction_setBufferTransparency().

Properties
`ASURFACE_TRANSACTION_TRANSPARENCY_OPAQUE`
`ASURFACE_TRANSACTION_TRANSPARENCY_TRANSLUCENT`
`ASURFACE_TRANSACTION_TRANSPARENCY_TRANSPARENT`

ASurfaceTransactionVisibility

 ASurfaceTransactionVisibility

Parameter for ASurfaceTransaction_setVisibility().

Properties
`ASURFACE_TRANSACTION_VISIBILITY_HIDE`
`ASURFACE_TRANSACTION_VISIBILITY_SHOW`

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_OnCommit

void(* ASurfaceTransaction_OnCommit)(void *_Null_unspecified context, ASurfaceTransactionStats *_Nonnull stats)

The ASurfaceTransaction_OnCommit callback is invoked when transaction is applied and the updates are ready to be presented.

This callback will be invoked before the ASurfaceTransaction_OnComplete callback.

This callback does not mean buffers have been released! It simply means that any new transactions applied will not overwrite the transaction for which we are receiving a callback and instead will be included in the next frame. If you are trying to avoid dropping frames (overwriting transactions), and unable to use timestamps (Which provide a more efficient solution), then this method provides a method to pace your transaction application.

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

Details

Parameters

`context`	Optional context provided by the client that is passed into the callback.
`stats`	Opaque handle that can be passed to ASurfaceTransactionStats functions to query information about the transaction. The handle is only valid during the callback. Present and release fences are not available for this callback. Querying them using ASurfaceTransactionStats_getPresentFenceFd and ASurfaceTransactionStats_getPreviousReleaseFenceFd will result in failure.

Available since API level 31.

ASurfaceTransaction_OnComplete

void(* ASurfaceTransaction_OnComplete)(void *_Null_unspecified context, ASurfaceTransactionStats *_Nonnull stats)

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.

Buffers which are replaced or removed from the scene in the transaction invoking this callback may be reused after this point.

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

Details

Parameters

`context`	Optional context provided by the client that is passed into the callback.
`stats`	Opaque handle that can be passed to ASurfaceTransactionStats functions to query information about the transaction. The handle is only valid during the callback.

Available since API level 29.

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.

Available since API level 26.

ASurfaceControl_acquire

void ASurfaceControl_acquire(
  ASurfaceControl *_Nonnull surface_control
)

Acquires a reference on the given ASurfaceControl object.

This prevents the object from being deleted until the reference is removed.

To release the reference, use the ASurfaceControl_release function.

Available since API level 31.

ASurfaceControl_create

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

See ASurfaceControl_createFromWindow.

Available since API level 29.

ASurfaceControl_createFromWindow

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

Creates an ASurfaceControl with either ANativeWindow or an ASurfaceControl as its parent.

debug_name is a debug name associated with this surface. It can be used to identify this surface in the SurfaceFlinger's layer tree. It must not be null.

The caller takes ownership of the ASurfaceControl returned and must release it using ASurfaceControl_release below.

By default the ASurfaceControl will be visible and display any buffer submitted. In addition, the default buffer submission control may release and not display all buffers that are submitted before receiving a callback for the previous buffer. See ASurfaceTransaction_setVisibility and ASurfaceTransaction_setEnableBackPressure to change the default behaviors after creation.

Available since API level 29.

ASurfaceControl_fromJava

ASurfaceControl *_Nonnull ASurfaceControl_fromJava(
  JNIEnv *_Nonnull env,
  jobject _Nonnull surfaceControlObj
)

Return the ASurfaceControl wrapped by a Java SurfaceControl object.

The caller takes ownership of the returned ASurfaceControl returned and must release it * using ASurfaceControl_release.

surfaceControlObj must be a non-null instance of android.view.SurfaceControl and isValid() must be true.

Available since API level 34.

ASurfaceControl_release

void ASurfaceControl_release(
  ASurfaceControl *_Nonnull surface_control
)

Removes a reference that was previously acquired with one of the following functions: ASurfaceControl_createFromWindow ASurfaceControl_create ANativeWindow_acquire The surface and its children may remain on display as long as their parent remains on display.

Available since API level 29.

ASurfaceTransactionStats_getASurfaceControls

void ASurfaceTransactionStats_getASurfaceControls(
  ASurfaceTransactionStats *_Nonnull surface_transaction_stats,
  ASurfaceControl *_Nullable *_Nullable *_Nonnull outASurfaceControls,
  size_t *_Nonnull 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.

Available since API level 29.

outASurfaceControlsSize returns the size of the ASurfaceControls array.

ASurfaceTransactionStats_getAcquireTime

int64_t ASurfaceTransactionStats_getAcquireTime(
  ASurfaceTransactionStats *_Nonnull surface_transaction_stats,
  ASurfaceControl *_Nonnull 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.

Available since API level 29.

ASurfaceTransactionStats_getLatchTime

int64_t ASurfaceTransactionStats_getLatchTime(
  ASurfaceTransactionStats *_Nonnull 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.

Available since API level 29.

ASurfaceTransactionStats_getPresentFenceFd

int ASurfaceTransactionStats_getPresentFenceFd(
  ASurfaceTransactionStats *_Nonnull 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. If a device does not support present fences, a -1 will be returned.

This query is not valid for ASurfaceTransaction_OnCommit callback.

Available since API level 29.

ASurfaceTransactionStats_getPreviousReleaseFenceFd

int ASurfaceTransactionStats_getPreviousReleaseFenceFd(
  ASurfaceTransactionStats *_Nonnull surface_transaction_stats,
  ASurfaceControl *_Nonnull 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() 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.

This query is not valid for ASurfaceTransaction_OnCommit callback.

Available since API level 29.

ASurfaceTransactionStats_releaseASurfaceControls

void ASurfaceTransactionStats_releaseASurfaceControls(
  ASurfaceControl *_Nonnull *_Nonnull surface_controls
)

Releases the array of ASurfaceControls that were returned by ASurfaceTransactionStats_getASurfaceControls().

Available since API level 29.

ASurfaceTransaction_apply

void ASurfaceTransaction_apply(
  ASurfaceTransaction *_Nonnull 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.

Available since API level 29.

ASurfaceTransaction_clearFrameRate

void ASurfaceTransaction_clearFrameRate(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control
)

Clears the frame rate which is set for surface_control.

This is equivalent to calling ASurfaceTransaction_setFrameRateWithChangeStrategy( transaction, 0, compatibility, changeFrameRateStrategy).

Usage of this API won't directly affect the application's frame production pipeline. However, because the system may change the display refresh rate, calls to this function may result in changes to Choreographer callback timings, and changes to the time interval at which the system releases buffers back to the application.

See ASurfaceTransaction_setFrameRateWithChangeStrategy()

You can register for changes in the refresh rate using AChoreographer_registerRefreshRateCallback.

See ASurfaceTransaction_setFrameRateWithChangeStrategy().

Available since API level 34.

ASurfaceTransaction_create

ASurfaceTransaction *_Nonnull ASurfaceTransaction_create()

The caller takes ownership of the transaction and must release it using ASurfaceTransaction_delete() below.

Available since API level 29.

ASurfaceTransaction_delete

void ASurfaceTransaction_delete(
  ASurfaceTransaction *_Nullable transaction
)

Destroys the transaction object.

Available since API level 29.

ASurfaceTransaction_fromJava

ASurfaceTransaction *_Nonnull ASurfaceTransaction_fromJava(
  JNIEnv *_Nonnull env,
  jobject _Nonnull transactionObj
)

Return the ASurfaceTransaction wrapped by a Java Transaction object.

The returned ASurfaceTransaction is still owned by the Java Transaction object is only valid while the Java Transaction object is alive. In particular, the returned transaction must NOT be deleted with ASurfaceTransaction_delete.

transactionObj must be a non-null instance of android.view.SurfaceControl.Transaction and close() must not already be called.

Available since API level 34.

ASurfaceTransaction_reparent

void ASurfaceTransaction_reparent(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  ASurfaceControl *_Nullable 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.

Available since API level 29.

ASurfaceTransaction_setBuffer

void ASurfaceTransaction_setBuffer(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  AHardwareBuffer *_Nonnull 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.

Note that the buffer must be allocated with AHARDWAREBUFFER_USAGE_GPU_SAMPLED_IMAGE as the surface control might be composited using the GPU.

Available since API level 29.

ASurfaceTransaction_setBufferAlpha

void ASurfaceTransaction_setBufferAlpha(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull 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.

Available since API level 29.

ASurfaceTransaction_setBufferDataSpace

void ASurfaceTransaction_setBufferDataSpace(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  enum 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.

Available since API level 29.

ASurfaceTransaction_setBufferTransform

void ASurfaceTransaction_setBufferTransform(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  int32_t transform
)

Available since API level 31.

Details

Parameters

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 transform use the NATIVE_WINDOW_TRANSFORM_* enum.

ASurfaceTransaction_setBufferTransparency

void ASurfaceTransaction_setBufferTransparency(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  enum ASurfaceTransactionTransparency 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.

Available since API level 29.

ASurfaceTransaction_setColor

void ASurfaceTransaction_setColor(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  float r,
  float g,
  float b,
  float alpha,
  enum 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.

Available since API level 29.

ASurfaceTransaction_setCrop

void ASurfaceTransaction_setCrop(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  const ARect *_Nonnull crop
)

Bounds the surface and its children to the bounds specified.

The crop and buffer size will be used to determine the bounds of the surface. If no crop is specified and the surface has no buffer, the surface bounds is only constrained by the size of its parent bounds.

Available since API level 31.

Details

Parameters

crop

The bounds of the crop to apply.

ASurfaceTransaction_setDamageRegion

void ASurfaceTransaction_setDamageRegion(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  const ARect *_Nullable 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.

Available since API level 29.

ASurfaceTransaction_setDesiredHdrHeadroom

void ASurfaceTransaction_setDesiredHdrHeadroom(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  float desiredHeadroom
)

Sets the desired hdr headroom for the layer.

See: ASurfaceTransaction_setExtendedRangeBrightness, prefer using this API for formats that conform to HDR standards like HLG or HDR10, that do not communicate a HDR/SDR ratio as part of generating the buffer.

While requesting a large desired ratio will result in the most dynamic range, voluntarily reducing the requested range can help improve battery life as well as can improve quality by ensuring greater bit depth is allocated to the luminance range in use.

Details

Parameters

`surface_control`	The layer whose desired hdr headroom is being specified
`desiredHeadroom`	The desired hdr/sdr ratio as represented as peakHdrBrightnessInNits / targetSdrWhitePointInNits. This can be used to communicate the max desired brightness range of the panel. The system may not be able to, or may choose not to, deliver the requested range.

Default value is 0.0f and indicates that the system will choose the best headroom for this surface control's content. Typically, this means that HLG/PQ encoded content will be displayed with some HDR headroom greater than 1.0.

When called after ASurfaceTransaction_setExtendedRangeBrightness, the desiredHeadroom will override the desiredRatio provided by ASurfaceTransaction_setExtendedRangeBrightness. Conversely, when called before ASurfaceTransaction_setExtendedRangeBrightness, the desiredRatio provided by ASurfaceTransaction_setExtendedRangeBrightness will override the desiredHeadroom.

Must be finite && >= 1.0f or 0.0f to indicate there is no desired headroom.

Available since API level 35.

ASurfaceTransaction_setDesiredPresentTime

void ASurfaceTransaction_setDesiredPresentTime(
  ASurfaceTransaction *_Nonnull 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.

Available since API level 29.

ASurfaceTransaction_setEnableBackPressure

void ASurfaceTransaction_setEnableBackPressure(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  bool enableBackPressure
)

Indicate whether to enable backpressure for buffer submission to a given SurfaceControl.

By default backpressure is disabled, which means submitting a buffer prior to receiving a callback for the previous buffer could lead to that buffer being "dropped". In cases where you are selecting for latency, this may be a desirable behavior! We had a new buffer ready, why shouldn't we show it?

When back pressure is enabled, each buffer will be required to be presented before it is released and the callback delivered (absent the whole SurfaceControl being removed).

Most apps are likely to have some sort of backpressure internally, e.g. you are waiting on the callback from frame N-2 before starting frame N. In high refresh rate scenarios there may not be much time between SurfaceFlinger completing frame N-1 (and therefore releasing buffer N-2) and beginning frame N. This means your app may not have enough time to respond in the callback. Using this flag and pushing buffers earlier for server side queuing will be advantageous in such cases.

Available since API level 31.

Details

Parameters

`transaction`	The transaction in which to make the change.
`surface_control`	The ASurfaceControl on which to control buffer backpressure behavior.
`enableBackPressure`	Whether to enable back pressure.

ASurfaceTransaction_setExtendedRangeBrightness

void ASurfaceTransaction_setExtendedRangeBrightness(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  float currentBufferRatio,
  float desiredRatio
)

Sets the desired extended range brightness for the layer.

This only applies for layers whose dataspace has RANGE_EXTENDED set on it. See: ASurfaceTransaction_setDesiredHdrHeadroom, prefer using this API for formats that encode an HDR/SDR ratio as part of generating the buffer.

Default value is 1.0f.

Details

Parameters

`surface_control`	The layer whose extended range brightness is being specified
`currentBufferRatio`	The current hdr/sdr ratio of the current buffer as represented as peakHdrBrightnessInNits / targetSdrWhitePointInNits. For example if the buffer was rendered with a target SDR whitepoint of 100nits and a max display brightness of 200nits, this should be set to 2.0f.

Transfer functions that encode their own brightness ranges, such as HLG or PQ, should also set this to 1.0f and instead communicate extended content brightness information via metadata such as CTA861_3 or SMPTE2086.

Must be finite && >= 1.0f

Details

Parameters

desiredRatio

The desired hdr/sdr ratio as represented as peakHdrBrightnessInNits / targetSdrWhitePointInNits. This can be used to communicate the max desired brightness range. This is similar to the "max luminance" value in other HDR metadata formats, but represented as a ratio of the target SDR whitepoint to the max display brightness. The system may not be able to, or may choose not to, deliver the requested range.

Default value is 1.0f and indicates that extended range brightness is not being used, so the resulting SDR or HDR behavior will be determined entirely by the dataspace being used (ie, typically SDR however PQ or HLG transfer functions will still result in HDR)

When called after ASurfaceTransaction_setDesiredHdrHeadroom, the desiredRatio will override the desiredHeadroom provided by ASurfaceTransaction_setDesiredHdrHeadroom. Conversely, when called before ASurfaceTransaction_setDesiredHdrHeadroom, the desiredHeadroom provided by . ASurfaceTransaction_setDesiredHdrHeadroom will override the desiredRatio.

                 Must be finite && >= 1.0f

Available since API level 34.

ASurfaceTransaction_setFrameRate

void ASurfaceTransaction_setFrameRate(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  float frameRate,
  int8_t compatibility
)

Same as ASurfaceTransaction_setFrameRateWithChangeStrategy(transaction, surface_control, frameRate, compatibility, ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS).

See ASurfaceTransaction_setFrameRateWithChangeStrategy().

Available since API level 30.

ASurfaceTransaction_setFrameRateWithChangeStrategy

void ASurfaceTransaction_setFrameRateWithChangeStrategy(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  float frameRate,
  int8_t compatibility,
  int8_t changeFrameRateStrategy
)

Sets the intended frame rate for surface_control.

On devices that are capable of running the display at different refresh rates, the system may choose a display refresh rate to better match this surface's frame rate. Usage of this API won't directly affect the application's frame production pipeline. However, because the system may change the display refresh rate, calls to this function may result in changes to Choreographer callback timings, and changes to the time interval at which the system releases buffers back to the application.

You can register for changes in the refresh rate using AChoreographer_registerRefreshRateCallback.

See ASurfaceTransaction_clearFrameRate().

Available since API level 31.

Details

Parameters

`frameRate`	is the intended frame rate of this surface, in frames per second. 0 is a special value that indicates the app will accept the system's choice for the display frame rate, which is the default behavior if this function isn't called. The frameRate param does not need to be a valid refresh rate for this device's display - e.g., it's fine to pass 30fps to a device that can only run the display at 60fps.
`compatibility`	The frame rate compatibility of this surface. The compatibility value may influence the system's choice of display frame rate. To specify a compatibility use the ANATIVEWINDOW_FRAME_RATE_COMPATIBILITY_* enum. This parameter is ignored when frameRate is 0.
`changeFrameRateStrategy`	Whether display refresh rate transitions caused by this surface should be seamless. A seamless transition is one that doesn't have any visual interruptions, such as a black screen for a second or two. See the ANATIVEWINDOW_CHANGE_FRAME_RATE_* values. This parameter is ignored when frameRate is 0.

ASurfaceTransaction_setFrameTimeline

void ASurfaceTransaction_setFrameTimeline(
  ASurfaceTransaction *_Nonnull transaction,
  AVsyncId vsyncId
)

Sets the frame timeline to use in SurfaceFlinger.

A frame timeline should be chosen based on the frame deadline the application can meet when rendering the frame and the application's desired presentation time. By setting a frame timeline, SurfaceFlinger tries to present the frame at the corresponding expected presentation time.

To receive frame timelines, a callback must be posted to Choreographer using AChoreographer_postVsyncCallback(). The vsyncId can then be extracted from the callback payload using AChoreographerFrameCallbackData_getFrameTimelineVsyncId().

Available since API level 33.

Details

Parameters

vsyncId

The vsync ID received from AChoreographer, setting the frame's presentation target to the corresponding expected presentation time and deadline from the frame to be rendered. A stale or invalid value will be ignored.

ASurfaceTransaction_setGeometry

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

Available since API level 29.

Details

Parameters

`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 transform use the NATIVE_WINDOW_TRANSFORM_* enum.

Deprecated. Use setCrop, setPosition, setBufferTransform, and setScale instead. Those functions provide well defined behavior and allows for more control by the apps. It also allows the caller to set different properties at different times, instead of having to specify all the desired properties at once.

ASurfaceTransaction_setHdrMetadata_cta861_3

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

Sets the CTA 861.3 "HDR Static Metadata Extension" static metadata on a surface.

When metadata is set to null, the framework does not use any cta861.3 metadata when rendering the surface's buffer.

Available since API level 29.

ASurfaceTransaction_setHdrMetadata_smpte2086

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

SMPTE ST 2086 "Mastering Display Color Volume" static metadata.

When metadata is set to null, the framework does not use any smpte2086 metadata when rendering the surface's buffer.

Available since API level 29.

ASurfaceTransaction_setOnCommit

void ASurfaceTransaction_setOnCommit(
  ASurfaceTransaction *_Nonnull transaction,
  void *_Null_unspecified context,
  ASurfaceTransaction_OnCommit _Nonnull func
)

Sets the callback that will be invoked when the updates from this transaction are applied and are ready to be presented.

This callback will be invoked before the ASurfaceTransaction_OnComplete callback.

Available since API level 31.

ASurfaceTransaction_setOnComplete

void ASurfaceTransaction_setOnComplete(
  ASurfaceTransaction *_Nonnull transaction,
  void *_Null_unspecified context,
  ASurfaceTransaction_OnComplete _Nonnull 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.

Available since API level 29.

ASurfaceTransaction_setPosition

void ASurfaceTransaction_setPosition(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  int32_t x,
  int32_t y
)

Specifies the position in the parent's space where the surface will be drawn.

Available since API level 31.

Details

Parameters

`x`	The x position to render the surface.
`y`	The y position to render the surface.

ASurfaceTransaction_setScale

void ASurfaceTransaction_setScale(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  float xScale,
  float yScale
)

Sets an x and y scale of a surface with (0, 0) as the centerpoint of the scale.

Available since API level 31.

Details

Parameters

`xScale`	The scale in the x direction. Must be greater than 0.
`yScale`	The scale in the y direction. Must be greater than 0.

ASurfaceTransaction_setVisibility

void ASurfaceTransaction_setVisibility(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull surface_control,
  enum ASurfaceTransactionVisibility 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.

Available since API level 29.

ASurfaceTransaction_setZOrder

void ASurfaceTransaction_setZOrder(
  ASurfaceTransaction *_Nonnull transaction,
  ASurfaceControl *_Nonnull 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.

Available since API level 29.

Native Activity

Summary

Enumerations

Typedefs

Variables

Functions

Structs

Enumerations

Anonymous Enum 107

Anonymous Enum 51

Anonymous Enum 52

ASurfaceTransactionTransparency

ASurfaceTransactionVisibility

Typedefs

ANativeActivity

ANativeActivityCallbacks

ANativeActivity_createFunc

ARect

ASurfaceControl

ASurfaceTransaction

ASurfaceTransactionStats

ASurfaceTransaction_OnCommit

ASurfaceTransaction_OnComplete

Variables

ANativeActivity_onCreate

Functions

ANativeActivity_finish

ANativeActivity_hideSoftInput

ANativeActivity_setWindowFlags

ANativeActivity_setWindowFormat

ANativeActivity_showSoftInput

ANativeWindow_fromSurface

ANativeWindow_toSurface

ASurfaceControl_acquire

ASurfaceControl_create

ASurfaceControl_createFromWindow

ASurfaceControl_fromJava

ASurfaceControl_release

ASurfaceTransactionStats_getASurfaceControls

ASurfaceTransactionStats_getAcquireTime

ASurfaceTransactionStats_getLatchTime

ASurfaceTransactionStats_getPresentFenceFd

ASurfaceTransactionStats_getPreviousReleaseFenceFd

ASurfaceTransactionStats_releaseASurfaceControls

ASurfaceTransaction_apply

ASurfaceTransaction_clearFrameRate

ASurfaceTransaction_create

ASurfaceTransaction_delete

ASurfaceTransaction_fromJava

ASurfaceTransaction_reparent

ASurfaceTransaction_setBuffer

ASurfaceTransaction_setBufferAlpha

ASurfaceTransaction_setBufferDataSpace

ASurfaceTransaction_setBufferTransform

ASurfaceTransaction_setBufferTransparency

ASurfaceTransaction_setColor

ASurfaceTransaction_setCrop

ASurfaceTransaction_setDamageRegion

ASurfaceTransaction_setDesiredHdrHeadroom

ASurfaceTransaction_setDesiredPresentTime

ASurfaceTransaction_setEnableBackPressure

ASurfaceTransaction_setExtendedRangeBrightness

ASurfaceTransaction_setFrameRate

ASurfaceTransaction_setFrameRateWithChangeStrategy

ASurfaceTransaction_setFrameTimeline

ASurfaceTransaction_setGeometry

ASurfaceTransaction_setHdrMetadata_cta861_3

ASurfaceTransaction_setHdrMetadata_smpte2086

ASurfaceTransaction_setOnCommit

ASurfaceTransaction_setOnComplete

ASurfaceTransaction_setPosition

ASurfaceTransaction_setScale

ASurfaceTransaction_setVisibility

ASurfaceTransaction_setZOrder