Native Window

#include <native_window.h>

ANativeWindow represents the producer end of an image queue.

Summary

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.

Enumerations

ANativeWindowTransform{
  ANATIVEWINDOW_TRANSFORM_IDENTITY = 0x00,
  ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL = 0x01,
  ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL = 0x02,
  ANATIVEWINDOW_TRANSFORM_ROTATE_90 = 0x04,
  ANATIVEWINDOW_TRANSFORM_ROTATE_180 = ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL | ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL,
  ANATIVEWINDOW_TRANSFORM_ROTATE_270 = ANATIVEWINDOW_TRANSFORM_ROTATE_180 | ANATIVEWINDOW_TRANSFORM_ROTATE_90
}
enum
Transforms that can be applied to buffers as they are displayed to a window.
ANativeWindow_LegacyFormat{
  WINDOW_FORMAT_RGBA_8888 = AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
  WINDOW_FORMAT_RGBX_8888 = AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM,
  WINDOW_FORMAT_RGB_565 = AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM
}
enum
Legacy window pixel format names, kept for backwards compatibility.

Typedefs

ANativeWindow typedef
struct ANativeWindow
Opaque type that provides access to a native window.
ANativeWindow_Buffer typedef
Struct that represents a windows buffer.

Functions

ANativeWindow_acquire(ANativeWindow *window)
void
Acquire a reference on the given ANativeWindow object.
ANativeWindow_getBuffersDataSpace(ANativeWindow *window)
int32_t
Get the dataspace of the buffers in window.
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_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_unlockAndPost(ANativeWindow *window)
int32_t
Unlock the window's drawing surface after previously locking it, posting the new buffer to the display.

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.

Properties
ANATIVEWINDOW_TRANSFORM_IDENTITY
ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL
ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL
ANATIVEWINDOW_TRANSFORM_ROTATE_180
ANATIVEWINDOW_TRANSFORM_ROTATE_270
ANATIVEWINDOW_TRANSFORM_ROTATE_90

ANativeWindow_LegacyFormat

 ANativeWindow_LegacyFormat

Legacy window pixel format names, kept for backwards compatibility.

New code and APIs should use AHARDWAREBUFFER_FORMAT_*.

Properties
WINDOW_FORMAT_RGBA_8888

Red: 8 bits, Green: 8 bits, Blue: 8 bits, Alpha: 8 bits.

WINDOW_FORMAT_RGBX_8888

Red: 8 bits, Green: 8 bits, Blue: 8 bits, Unused: 8 bits.

WINDOW_FORMAT_RGB_565

Red: 5 bits, Green: 6 bits, Blue: 5 bits.

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_getBuffersDataSpace

int32_t ANativeWindow_getBuffersDataSpace(
  ANativeWindow *window
)

Get the dataspace of the buffers in window.

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

Details
Parameters
dataSpace
data space of all buffers queued after this call.
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
width
width of the buffers in pixels.
height
height of the buffers in pixels.
format
one of the AHardwareBuffer_Format constants.
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.

Details
Parameters
transform
combination of ANativeWindowTransform flags
Returns
0 for success, or -EINVAL if transform is invalid

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.