Native Activity

The AInputReceiver_onKeyEvent callback is invoked when the registered input channel receives a key event.

Available since API level 35.

The AInputReceiver_onMotionEvent callback is invoked when the registered input channel receives a motion event.

Available since API level 35.

AInputTransferToken can be used to request focus on or to transfer touch gesture to and from an embedded SurfaceControl.

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.

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.

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.

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.

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 is a collection of updates to the surface tree that must be applied atomically.

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.

The ASurfaceTransaction_OnBufferRelease callback is invoked when a buffer that was passed in ASurfaceTransaction_setBuffer is ready to be reused.

This callback is guaranteed to be invoked if ASurfaceTransaction_setBuffer is called with a non null buffer. If the buffer in the transaction is replaced via another call to ASurfaceTransaction_setBuffer, the callback will be invoked immediately. Otherwise the callback will be invoked before the ASurfaceTransaction_OnComplete callback after the buffer was presented.

If this callback is set, caller should not release the buffer using the ASurfaceTransaction_OnComplete.

THREADING The callback can be invoked on any thread.

Available since API level 36.

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.

Available since API level 31.

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.

Starting with API level 36, prefer using ASurfaceTransaction_OnBufferRelease to listen to when a buffer is ready to be reused.

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

Available since API level 29.

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.

Creates a AInputReceiverCallbacks object that is used when registering for an AInputReceiver.

This must be released using AInputReceiverCallbacks_release

Available since API level 35.

Releases the AInputReceiverCallbacks.

This must be called on the same looper thread the AInputReceiver was created with. The receiver will not invoke any callbacks once it's been released.

Available since API level 35

Sets a AInputReceiver_onKeyEvent callback for an AInputReceiverCallbacks.

Available since API level 35.

Sets a AInputReceiver_onMotionEvent callback for an AInputReceiverCallbacks.

Available since API level 35.

Registers an input receiver for an ASurfaceControl that will receive batched input event.

For those events that are batched, the invocation will happen once per AChoreographer frame, and other input events will be delivered immediately.

This is different from AInputReceiver_createUnbatchedInputReceiver in that the input events are received batched. The caller must invoke AInputReceiver_release to clean up the resources when no longer needing to use the input receiver.

Returns the reference to AInputReceiver to clean up resources when done.

Available since API level 35.

Registers an input receiver for an ASurfaceControl that will receive every input event.

This is different from AInputReceiver_createBatchedInputReceiver in that the input events are received unbatched. The caller must invoke AInputReceiver_release to clean up the resources when no longer needing to use the input receiver.

Returns the reference to AInputReceiver to clean up resources when done.

Available since API level 35.

Returns the AInputTransferToken that can be used to transfer touch gesture to or from other windows.

This InputTransferToken is associated with the SurfaceControl that registered an input receiver and can be used with the host token for things like transfer touch gesture via WindowManager::transferTouchGesture().

This must be released with AInputTransferToken_release.

Available since API level 35.

Unregisters the input channel and deletes the AInputReceiver.

This must be called on the same looper thread it was created with.

Available since API level 35.

Return the AInputTransferToken wrapped by a Java InputTransferToken object.

This must be released using AInputTransferToken_release

inputTransferTokenObj must be a non-null instance of android.window.InputTransferToken.

Available since API level 35.

Removes a reference that was previously acquired in native.

Available since API level 35.

Return the Java InputTransferToken object that wraps AInputTransferToken.

aInputTransferToken must be non null and the returned value is an object of instance android.window.InputTransferToken.

Available since API level 35.

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.

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.

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.

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.

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.

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.

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.

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.

See ASurfaceControl_createFromWindow.

Available since API level 29.

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.

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.

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.

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.

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.

Deprecated. This may return SIGNAL_PENDING because the stats can arrive before the acquire fence has signaled, depending on internal timing differences. Therefore the caller should use the acquire fence passed in to setBuffer and query the signal time.

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.

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.

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.

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

Available since API level 29.

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.

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.

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

Available since API level 29.

Destroys the transaction object.

Available since API level 29.

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.

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.

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.

Starting with API level 36, prefer using ASurfaceTransaction_setBufferWithRelease to set a buffer and a callback which will be invoked when the buffer is ready to be reused.

Available since API level 29.

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.

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.

Available since API level 31.

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.

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.

When the buffer is ready to be reused, the ASurfaceTransaction_OnBufferRelease callback will be invoked. If the buffer is null, the callback will not be invoked.

Available since API level 36.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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

See ASurfaceTransaction_setFrameRateWithChangeStrategy().

Available since API level 30.

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.

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.

Available since API level 29.

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.

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.

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.

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.

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.

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

Available since API level 31.

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

Available since API level 31.

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.

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.