Native Window
#include <native_window.h>
ANativeWindow represents the producer end of an image queue.
Summary
Parcelable support for ANativeWindow.
It is the C counterpart of the android.view.Surface object in Java, and can be converted both ways. Depending on the consumer, images submitted to ANativeWindow can be shown on the display or sent to other consumers, such as video encoders.
Can be used with libbinder_ndk
Enumerations |
|
---|---|
ANativeWindowTransform{
|
enum Transforms that can be applied to buffers as they are displayed to a window. |
ANativeWindow_ChangeFrameRateStrategy{
|
enum Change frame rate strategy value for ANativeWindow_setFrameRate. |
ANativeWindow_FrameRateCompatibility{
|
enum Compatibility value for ANativeWindow_setFrameRate. |
ANativeWindow_LegacyFormat{
|
enum Legacy window pixel format names, kept for backwards compatibility. |
Typedefs |
|
---|---|
ANativeWindow
|
typedefstruct ANativeWindow
Opaque type that provides access to a native window. |
ANativeWindow_Buffer
|
typedefstruct ANativeWindow_Buffer
Struct that represents a windows buffer. |
Functions |
|
---|---|
ANativeWindow_acquire(ANativeWindow *window)
|
void
Acquire a reference on the given ANativeWindow object.
|
ANativeWindow_clearFrameRate(ANativeWindow *window)
|
int32_t
Clears the frame rate which is set for this window.
|
ANativeWindow_getBuffersDataSpace(ANativeWindow *window)
|
int32_t
Get the dataspace of the buffers in window.
|
ANativeWindow_getBuffersDefaultDataSpace(ANativeWindow *window)
|
int32_t
Get the default dataspace of the buffers in window as set by the consumer.
|
ANativeWindow_getFormat(ANativeWindow *window)
|
int32_t
Return the current pixel format (AHARDWAREBUFFER_FORMAT_*) of the window surface.
|
ANativeWindow_getHeight(ANativeWindow *window)
|
int32_t
Return the current height in pixels of the window surface.
|
ANativeWindow_getWidth(ANativeWindow *window)
|
int32_t
Return the current width in pixels of the window surface.
|
ANativeWindow_lock(ANativeWindow *window, ANativeWindow_Buffer *outBuffer, ARect *inOutDirtyBounds)
|
int32_t
Lock the window's next drawing surface for writing.
|
ANativeWindow_readFromParcel(const AParcel *_Nonnull parcel, ANativeWindow *_Nullable *_Nonnull outWindow)
|
Read an ANativeWindow from a AParcel.
|
ANativeWindow_release(ANativeWindow *window)
|
void
Remove a reference that was previously acquired with ANativeWindow_acquire().
|
ANativeWindow_setBuffersDataSpace(ANativeWindow *window, int32_t dataSpace)
|
int32_t
All buffers queued after this call will be associated with the dataSpace parameter specified.
|
ANativeWindow_setBuffersGeometry(ANativeWindow *window, int32_t width, int32_t height, int32_t format)
|
int32_t
Change the format and size of the window buffers.
|
ANativeWindow_setBuffersTransform(ANativeWindow *window, int32_t transform)
|
int32_t
Set a transform that will be applied to future buffers posted to the window.
|
ANativeWindow_setFrameRate(ANativeWindow *window, float frameRate, int8_t compatibility)
|
int32_t
Same as ANativeWindow_setFrameRateWithChangeStrategy(window, frameRate, compatibility, ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS).
|
ANativeWindow_setFrameRateWithChangeStrategy(ANativeWindow *window, float frameRate, int8_t compatibility, int8_t changeFrameRateStrategy)
|
int32_t
Sets the intended frame rate for this window.
|
ANativeWindow_tryAllocateBuffers(ANativeWindow *window)
|
void
Provides a hint to the window that buffers should be preallocated ahead of time.
|
ANativeWindow_unlockAndPost(ANativeWindow *window)
|
int32_t
Unlock the window's drawing surface after previously locking it, posting the new buffer to the display.
|
ANativeWindow_writeToParcel(ANativeWindow *_Nonnull window, AParcel *_Nonnull parcel)
|
Write an ANativeWindow to an AParcel.
|
Structs |
|
---|---|
ANativeWindow_Buffer |
Struct that represents a windows buffer. |
Enumerations
ANativeWindowTransform
ANativeWindowTransform
Transforms that can be applied to buffers as they are displayed to a window.
Supported transforms are any combination of horizontal mirror, vertical mirror, and clockwise 90 degree rotation, in that order. Rotations of 180 and 270 degrees are made up of those basic transforms.
ANativeWindow_ChangeFrameRateStrategy
ANativeWindow_ChangeFrameRateStrategy
Change frame rate strategy value for ANativeWindow_setFrameRate.
ANativeWindow_FrameRateCompatibility
ANativeWindow_FrameRateCompatibility
Compatibility value for ANativeWindow_setFrameRate.
ANativeWindow_LegacyFormat
ANativeWindow_LegacyFormat
Legacy window pixel format names, kept for backwards compatibility.
New code and APIs should use AHARDWAREBUFFER_FORMAT_*.
Typedefs
ANativeWindow
struct ANativeWindow ANativeWindow
Opaque type that provides access to a native window.
A pointer can be obtained using ANativeWindow_fromSurface().
ANativeWindow_Buffer
struct ANativeWindow_Buffer ANativeWindow_Buffer
Struct that represents a windows buffer.
A pointer can be obtained using ANativeWindow_lock().
Functions
ANativeWindow_acquire
void ANativeWindow_acquire( ANativeWindow *window )
Acquire a reference on the given ANativeWindow object.
This prevents the object from being deleted until the reference is removed.
ANativeWindow_clearFrameRate
int32_t ANativeWindow_clearFrameRate( ANativeWindow *window )
Clears the frame rate which is set for this window.
This is equivalent to calling ANativeWindow_setFrameRateWithChangeStrategy(window, 0, compatibility, changeFrameRateStrategy).
Usage of this API won't introduce frame rate throttling, or affect other aspects of 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.
Note that this only has an effect for windows presented on the display. If this ANativeWindow is consumed by something other than the system compositor, e.g. a media codec, this call has no effect.
You can register for changes in the refresh rate using AChoreographer_registerRefreshRateCallback.
See ANativeWindow_setFrameRateWithChangeStrategy().
Available since API level 34.
Details | |||
---|---|---|---|
Parameters |
|
||
Returns |
0 for success, -EINVAL if the window value is invalid.
|
ANativeWindow_getBuffersDataSpace
int32_t ANativeWindow_getBuffersDataSpace( ANativeWindow *window )
Get the dataspace of the buffers in window.
Available since API level 28.
Details | |
---|---|
Returns |
the dataspace of buffers in window, ADATASPACE_UNKNOWN is returned if dataspace is unknown, or -EINVAL if window is invalid.
|
ANativeWindow_getBuffersDefaultDataSpace
int32_t ANativeWindow_getBuffersDefaultDataSpace( ANativeWindow *window )
Get the default dataspace of the buffers in window as set by the consumer.
Available since API level 34.
Details | |
---|---|
Returns |
the dataspace of buffers in window, ADATASPACE_UNKNOWN is returned if dataspace is unknown, or -EINVAL if window is invalid.
|
ANativeWindow_getFormat
int32_t ANativeWindow_getFormat( ANativeWindow *window )
Return the current pixel format (AHARDWAREBUFFER_FORMAT_*) of the window surface.
Details | |
---|---|
Returns |
a negative value on error.
|
ANativeWindow_getHeight
int32_t ANativeWindow_getHeight( ANativeWindow *window )
Return the current height in pixels of the window surface.
Details | |
---|---|
Returns |
a negative value on error.
|
ANativeWindow_getWidth
int32_t ANativeWindow_getWidth( ANativeWindow *window )
Return the current width in pixels of the window surface.
Details | |
---|---|
Returns |
negative value on error.
|
ANativeWindow_lock
int32_t ANativeWindow_lock( ANativeWindow *window, ANativeWindow_Buffer *outBuffer, ARect *inOutDirtyBounds )
Lock the window's next drawing surface for writing.
inOutDirtyBounds is used as an in/out parameter, upon entering the function, it contains the dirty region, that is, the region the caller intends to redraw. When the function returns, inOutDirtyBounds is updated with the actual area the caller needs to redraw this region is often extended by ANativeWindow_lock.
Details | |
---|---|
Returns |
0 for success, or a negative value on error.
|
ANativeWindow_readFromParcel
binder_status_t ANativeWindow_readFromParcel( const AParcel *_Nonnull parcel, ANativeWindow *_Nullable *_Nonnull outWindow )
Read an ANativeWindow from a AParcel.
The output buffer will have an initial reference acquired and will need to be released with ANativeWindow_release.
Available since API level 34.
Details | |
---|---|
Returns |
STATUS_OK on success STATUS_BAD_VALUE if the parcel or outBuffer is null, or if there's an issue deserializing (eg, corrupted parcel) STATUS_BAD_TYPE if the parcel's current data position is not that of an ANativeWindow type STATUS_NO_MEMORY if an allocation fails
|
ANativeWindow_release
void ANativeWindow_release( ANativeWindow *window )
Remove a reference that was previously acquired with ANativeWindow_acquire().
ANativeWindow_setBuffersDataSpace
int32_t ANativeWindow_setBuffersDataSpace( ANativeWindow *window, int32_t dataSpace )
All buffers queued after this call will be associated with the dataSpace parameter specified.
dataSpace specifies additional information about the buffer. For example, it can be used to convey the color space of the image data in the buffer, or it can be used to indicate that the buffers contain depth measurement data instead of color images. The default dataSpace is 0, ADATASPACE_UNKNOWN, unless it has been overridden by the producer.
Available since API level 28.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Returns |
0 for success, -EINVAL if window is invalid or the dataspace is not supported.
|
ANativeWindow_setBuffersGeometry
int32_t ANativeWindow_setBuffersGeometry( ANativeWindow *window, int32_t width, int32_t height, int32_t format )
Change the format and size of the window buffers.
The width and height control the number of pixels in the buffers, not the dimensions of the window on screen. If these are different than the window's physical size, then its buffer will be scaled to match that size when compositing it to the screen. The width and height must be either both zero or both non-zero.
For all of these parameters, if 0 is supplied then the window's base value will come back in force.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameters |
|
||||||||
Returns |
0 for success, or a negative value on error.
|
ANativeWindow_setBuffersTransform
int32_t ANativeWindow_setBuffersTransform( ANativeWindow *window, int32_t transform )
Set a transform that will be applied to future buffers posted to the window.
Available since API level 26.
Details | |||||
---|---|---|---|---|---|
Parameters |
|
||||
Returns |
0 for success, or -EINVAL if
transform is invalid |
ANativeWindow_setFrameRate
int32_t ANativeWindow_setFrameRate( ANativeWindow *window, float frameRate, int8_t compatibility )
Same as ANativeWindow_setFrameRateWithChangeStrategy(window, frameRate, compatibility, ANATIVEWINDOW_CHANGE_FRAME_RATE_ONLY_IF_SEAMLESS).
See ANativeWindow_setFrameRateWithChangeStrategy().
Available since API level 30.
ANativeWindow_setFrameRateWithChangeStrategy
int32_t ANativeWindow_setFrameRateWithChangeStrategy( ANativeWindow *window, float frameRate, int8_t compatibility, int8_t changeFrameRateStrategy )
Sets the intended frame rate for this window.
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 window's frame rate. Usage of this API won't introduce frame rate throttling, or affect other aspects of 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.
Note that this only has an effect for windows presented on the display. If this ANativeWindow is consumed by something other than the system compositor, e.g. a media codec, this call has no effect.
You can register for changes in the refresh rate using AChoreographer_registerRefreshRateCallback.
See ANativeWindow_clearFrameRate().
Available since API level 31.
Details | |||||||||
---|---|---|---|---|---|---|---|---|---|
Parameters |
|
||||||||
Returns |
0 for success, -EINVAL if the window, frame rate, or compatibility value are invalid.
|
ANativeWindow_tryAllocateBuffers
void ANativeWindow_tryAllocateBuffers( ANativeWindow *window )
Provides a hint to the window that buffers should be preallocated ahead of time.
Note that the window implementation is not guaranteed to preallocate any buffers, for instance if an implementation disallows allocation of new buffers, or if there is insufficient memory in the system to preallocate additional buffers
Available since API level 30.
ANativeWindow_unlockAndPost
int32_t ANativeWindow_unlockAndPost( ANativeWindow *window )
Unlock the window's drawing surface after previously locking it, posting the new buffer to the display.
Details | |
---|---|
Returns |
0 for success, or a negative value on error.
|
ANativeWindow_writeToParcel
binder_status_t ANativeWindow_writeToParcel( ANativeWindow *_Nonnull window, AParcel *_Nonnull parcel )
Write an ANativeWindow to an AParcel.
Available since API level 34.
Details | |
---|---|
Returns |
STATUS_OK on success. STATUS_BAD_VALUE if either buffer or parcel is null, or if the ANativeWindow* fails to serialize (eg, internally corrupted) STATUS_NO_MEMORY if the parcel runs out of space to store the buffer & is unable to allocate more STATUS_FDS_NOT_ALLOWED if the parcel does not allow storing FDs
|