Home | History | Annotate | Download | only in hwui 
      1 /*
      2  * Copyright (C) 2013 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 #ifndef ANDROID_HWUI_PIXEL_BUFFER_H
     18 #define ANDROID_HWUI_PIXEL_BUFFER_H
     19 
     20 #include <GLES3/gl3.h>
     21 #include <cutils/log.h>
     22 
     23 namespace android {
     24 namespace uirenderer {
     25 
     26 /**
     27  * Represents a pixel buffer. A pixel buffer will be backed either by a
     28  * PBO on OpenGL ES 3.0 and higher or by an array of uint8_t on other
     29  * versions. If the buffer is backed by a PBO it will of type
     30  * GL_PIXEL_UNPACK_BUFFER.
     31  *
     32  * To read from or write into a PixelBuffer you must first map the
     33  * buffer using the map(AccessMode) method. This method returns a
     34  * pointer to the beginning of the buffer.
     35  *
     36  * Before the buffer can be used by the GPU, for instance to upload
     37  * a texture, you must first unmap the buffer. To do so, call the
     38  * unmap() method.
     39  *
     40  * Mapping and unmapping a PixelBuffer can have the side effect of
     41  * changing the currently active GL_PIXEL_UNPACK_BUFFER. It is
     42  * therefore recommended to call Caches::unbindPixelbuffer() after
     43  * using a PixelBuffer to upload to a texture.
     44  */
     45 class PixelBuffer {
     46 public:
     47     enum BufferType {
     48         kBufferType_Auto,
     49         kBufferType_CPU
     50     };
     51 
     52     enum AccessMode {
     53         kAccessMode_None = 0,
     54         kAccessMode_Read = GL_MAP_READ_BIT,
     55         kAccessMode_Write = GL_MAP_WRITE_BIT,
     56         kAccessMode_ReadWrite = GL_MAP_READ_BIT | GL_MAP_WRITE_BIT
     57     };
     58 
     59     /**
     60      * Creates a new PixelBuffer object with the specified format and
     61      * dimensions. The buffer is immediately allocated.
     62      *
     63      * The buffer type specifies how the buffer should be allocated.
     64      * By default this method will automatically choose whether to allocate
     65      * a CPU or GPU buffer.
     66      */
     67     static PixelBuffer* create(GLenum format, uint32_t width, uint32_t height,
     68             BufferType type = kBufferType_Auto);
     69 
     70     virtual ~PixelBuffer() {
     71     }
     72 
     73     /**
     74      * Returns the format of this render buffer.
     75      */
     76     GLenum getFormat() const {
     77         return mFormat;
     78     }
     79 
     80     /**
     81      * Maps this before with the specified access mode. This method
     82      * returns a pointer to the region of memory where the buffer was
     83      * mapped.
     84      *
     85      * If the buffer is already mapped when this method is invoked,
     86      * this method will return the previously mapped pointer. The
     87      * access mode can only be changed by calling unmap() first.
     88      *
     89      * The specified access mode cannot be kAccessMode_None.
     90      */
     91     virtual uint8_t* map(AccessMode mode = kAccessMode_ReadWrite) = 0;
     92 
     93     /**
     94      * Unmaps this buffer, if needed. After the buffer is unmapped,
     95      * the pointer previously returned by map() becomes invalid and
     96      * should not be used. After calling this method, getMappedPointer()
     97      * will always return NULL.
     98      */
     99     virtual void unmap() = 0;
    100 
    101     /**
    102      * Returns the current access mode for this buffer. If the buffer
    103      * is not mapped, this method returns kAccessMode_None.
    104      */
    105     AccessMode getAccessMode() const {
    106         return mAccessMode;
    107     }
    108 
    109     /**
    110      * Returns the currently mapped pointer. Returns NULL if the buffer
    111      * is not mapped.
    112      */
    113     virtual uint8_t* getMappedPointer() const = 0;
    114 
    115     /**
    116      * Upload the specified rectangle of this pixel buffer as a
    117      * GL_TEXTURE_2D texture. Calling this method will trigger
    118      * an unmap() if necessary.
    119      */
    120     virtual void upload(uint32_t x, uint32_t y, uint32_t width, uint32_t height, int offset) = 0;
    121 
    122     /**
    123      * Upload the specified rectangle of this pixel buffer as a
    124      * GL_TEXTURE_2D texture. Calling this method will trigger
    125      * an unmap() if necessary.
    126      *
    127      * This is a convenience function provided to save callers the
    128      * trouble of computing the offset parameter.
    129      */
    130     void upload(uint32_t x, uint32_t y, uint32_t width, uint32_t height) {
    131         upload(x, y, width, height, getOffset(x, y));
    132     }
    133 
    134     /**
    135      * Returns the width of the render buffer in pixels.
    136      */
    137     uint32_t getWidth() const {
    138         return mWidth;
    139     }
    140 
    141     /**
    142      * Returns the height of the render buffer in pixels.
    143      */
    144     uint32_t getHeight() const {
    145         return mHeight;
    146     }
    147 
    148     /**
    149      * Returns the size of this pixel buffer in bytes.
    150      */
    151     uint32_t getSize() const {
    152         return mWidth * mHeight * formatSize(mFormat);
    153     }
    154 
    155     /**
    156      * Returns the offset of a pixel in this pixel buffer, in bytes.
    157      */
    158     uint32_t getOffset(uint32_t x, uint32_t y) const {
    159         return (y * mWidth + x) * formatSize(mFormat);
    160     }
    161 
    162     /**
    163      * Returns the number of bytes per pixel in the specified format.
    164      *
    165      * Supported formats:
    166      *      GL_ALPHA
    167      *      GL_RGBA
    168      */
    169     static uint32_t formatSize(GLenum format) {
    170         switch (format) {
    171             case GL_ALPHA:
    172                 return 1;
    173             case GL_RGBA:
    174                 return 4;
    175         }
    176         return 0;
    177     }
    178 
    179     /**
    180      * Returns the alpha channel offset in the specified format.
    181      *
    182      * Supported formats:
    183      *      GL_ALPHA
    184      *      GL_RGBA
    185      */
    186     static uint32_t formatAlphaOffset(GLenum format) {
    187         switch (format) {
    188             case GL_ALPHA:
    189                 return 0;
    190             case GL_RGBA:
    191                 return 3;
    192         }
    193 
    194         ALOGE("unsupported format: %d",format);
    195         return 0;
    196     }
    197 
    198 protected:
    199     /**
    200      * Creates a new render buffer in the specified format and dimensions.
    201      * The format must be GL_ALPHA or GL_RGBA.
    202      */
    203     PixelBuffer(GLenum format, uint32_t width, uint32_t height):
    204             mFormat(format), mWidth(width), mHeight(height), mAccessMode(kAccessMode_None) {
    205     }
    206 
    207     GLenum mFormat;
    208 
    209     uint32_t mWidth;
    210     uint32_t mHeight;
    211 
    212     AccessMode mAccessMode;
    213 
    214 }; // class PixelBuffer
    215 
    216 }; // namespace uirenderer
    217 }; // namespace android
    218 
    219 #endif // ANDROID_HWUI_PIXEL_BUFFER_H
    220