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