Home | History | Annotate | Download | only in android
      1 /*
      2  * Copyright (C) 2010 The Android Open Source Project
      3  *
      4  * Licensed under the Apache License, Version 2.0 (the "License");
      5  * you may not use this file except in compliance with the License.
      6  * You may obtain a copy of the License at
      7  *
      8  *      http://www.apache.org/licenses/LICENSE-2.0
      9  *
     10  * Unless required by applicable law or agreed to in writing, software
     11  * distributed under the License is distributed on an "AS IS" BASIS,
     12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     13  * See the License for the specific language governing permissions and
     14  * limitations under the License.
     15  */
     16 
     17 /**
     18  * @addtogroup NativeActivity Native Activity
     19  * @{
     20  */
     21 
     22 /**
     23  * @file native_window.h
     24  * @brief API for accessing a native window.
     25  */
     26 
     27 #ifndef ANDROID_NATIVE_WINDOW_H
     28 #define ANDROID_NATIVE_WINDOW_H
     29 
     30 #include <sys/cdefs.h>
     31 
     32 #include <android/hardware_buffer.h>
     33 #include <android/rect.h>
     34 
     35 #ifdef __cplusplus
     36 extern "C" {
     37 #endif
     38 
     39 /**
     40  * Legacy window pixel format names, kept for backwards compatibility.
     41  * New code and APIs should use AHARDWAREBUFFER_FORMAT_*.
     42  */
     43 enum {
     44     // NOTE: these values must match the values from graphics/common/x.x/types.hal
     45 
     46     /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Alpha: 8 bits. **/
     47     WINDOW_FORMAT_RGBA_8888          = AHARDWAREBUFFER_FORMAT_R8G8B8A8_UNORM,
     48     /** Red: 8 bits, Green: 8 bits, Blue: 8 bits, Unused: 8 bits. **/
     49     WINDOW_FORMAT_RGBX_8888          = AHARDWAREBUFFER_FORMAT_R8G8B8X8_UNORM,
     50     /** Red: 5 bits, Green: 6 bits, Blue: 5 bits. **/
     51     WINDOW_FORMAT_RGB_565            = AHARDWAREBUFFER_FORMAT_R5G6B5_UNORM,
     52 };
     53 
     54 /**
     55  * Transforms that can be applied to buffers as they are displayed to a window.
     56  *
     57  * Supported transforms are any combination of horizontal mirror, vertical
     58  * mirror, and clockwise 90 degree rotation, in that order. Rotations of 180
     59  * and 270 degrees are made up of those basic transforms.
     60  */
     61 enum ANativeWindowTransform {
     62     ANATIVEWINDOW_TRANSFORM_IDENTITY            = 0x00,
     63     ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL   = 0x01,
     64     ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL     = 0x02,
     65     ANATIVEWINDOW_TRANSFORM_ROTATE_90           = 0x04,
     66 
     67     ANATIVEWINDOW_TRANSFORM_ROTATE_180          = ANATIVEWINDOW_TRANSFORM_MIRROR_HORIZONTAL |
     68                                                   ANATIVEWINDOW_TRANSFORM_MIRROR_VERTICAL,
     69     ANATIVEWINDOW_TRANSFORM_ROTATE_270          = ANATIVEWINDOW_TRANSFORM_ROTATE_180 |
     70                                                   ANATIVEWINDOW_TRANSFORM_ROTATE_90,
     71 };
     72 
     73 struct ANativeWindow;
     74 /**
     75  * Opaque type that provides access to a native window.
     76  *
     77  * A pointer can be obtained using {@link ANativeWindow_fromSurface()}.
     78  */
     79 typedef struct ANativeWindow ANativeWindow;
     80 
     81 /**
     82  * Struct that represents a windows buffer.
     83  *
     84  * A pointer can be obtained using {@link ANativeWindow_lock()}.
     85  */
     86 typedef struct ANativeWindow_Buffer {
     87     // The number of pixels that are show horizontally.
     88     int32_t width;
     89 
     90     // The number of pixels that are shown vertically.
     91     int32_t height;
     92 
     93     // The number of *pixels* that a line in the buffer takes in
     94     // memory. This may be >= width.
     95     int32_t stride;
     96 
     97     // The format of the buffer. One of AHARDWAREBUFFER_FORMAT_*
     98     int32_t format;
     99 
    100     // The actual bits.
    101     void* bits;
    102 
    103     // Do not touch.
    104     uint32_t reserved[6];
    105 } ANativeWindow_Buffer;
    106 
    107 /**
    108  * Acquire a reference on the given {@link ANativeWindow} object. This prevents the object
    109  * from being deleted until the reference is removed.
    110  */
    111 void ANativeWindow_acquire(ANativeWindow* window);
    112 
    113 /**
    114  * Remove a reference that was previously acquired with {@link ANativeWindow_acquire()}.
    115  */
    116 void ANativeWindow_release(ANativeWindow* window);
    117 
    118 /**
    119  * Return the current width in pixels of the window surface.
    120  *
    121  * \return negative value on error.
    122  */
    123 int32_t ANativeWindow_getWidth(ANativeWindow* window);
    124 
    125 /**
    126  * Return the current height in pixels of the window surface.
    127  *
    128  * \return a negative value on error.
    129  */
    130 int32_t ANativeWindow_getHeight(ANativeWindow* window);
    131 
    132 /**
    133  * Return the current pixel format (AHARDWAREBUFFER_FORMAT_*) of the window surface.
    134  *
    135  * \return a negative value on error.
    136  */
    137 int32_t ANativeWindow_getFormat(ANativeWindow* window);
    138 
    139 /**
    140  * Change the format and size of the window buffers.
    141  *
    142  * The width and height control the number of pixels in the buffers, not the
    143  * dimensions of the window on screen. If these are different than the
    144  * window's physical size, then its buffer will be scaled to match that size
    145  * when compositing it to the screen. The width and height must be either both zero
    146  * or both non-zero.
    147  *
    148  * For all of these parameters, if 0 is supplied then the window's base
    149  * value will come back in force.
    150  *
    151  * \param width width of the buffers in pixels.
    152  * \param height height of the buffers in pixels.
    153  * \param format one of AHARDWAREBUFFER_FORMAT_* constants.
    154  * \return 0 for success, or a negative value on error.
    155  */
    156 int32_t ANativeWindow_setBuffersGeometry(ANativeWindow* window,
    157         int32_t width, int32_t height, int32_t format);
    158 
    159 /**
    160  * Lock the window's next drawing surface for writing.
    161  * inOutDirtyBounds is used as an in/out parameter, upon entering the
    162  * function, it contains the dirty region, that is, the region the caller
    163  * intends to redraw. When the function returns, inOutDirtyBounds is updated
    164  * with the actual area the caller needs to redraw -- this region is often
    165  * extended by {@link ANativeWindow_lock}.
    166  *
    167  * \return 0 for success, or a negative value on error.
    168  */
    169 int32_t ANativeWindow_lock(ANativeWindow* window, ANativeWindow_Buffer* outBuffer,
    170         ARect* inOutDirtyBounds);
    171 
    172 /**
    173  * Unlock the window's drawing surface after previously locking it,
    174  * posting the new buffer to the display.
    175  *
    176  * \return 0 for success, or a negative value on error.
    177  */
    178 int32_t ANativeWindow_unlockAndPost(ANativeWindow* window);
    179 
    180 #if __ANDROID_API__ >= __ANDROID_API_O__
    181 
    182 /**
    183  * Set a transform that will be applied to future buffers posted to the window.
    184  *
    185  * \param transform combination of {@link ANativeWindowTransform} flags
    186  * \return 0 for success, or -EINVAL if \p transform is invalid
    187  */
    188 int32_t ANativeWindow_setBuffersTransform(ANativeWindow* window, int32_t transform);
    189 
    190 #endif // __ANDROID_API__ >= __ANDROID_API_O__
    191 
    192 #ifdef __cplusplus
    193 };
    194 #endif
    195 
    196 #endif // ANDROID_NATIVE_WINDOW_H
    197 
    198 /** @} */
    199