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 pixe 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      * Returns the width of the render buffer in pixels.
    123      */
    124     uint32_t getWidth() const {
    125         return mWidth;
    126     }
    127 
    128     /**
    129      * Returns the height of the render buffer in pixels.
    130      */
    131     uint32_t getHeight() const {
    132         return mHeight;
    133     }
    134 
    135     /**
    136      * Returns the size of this pixel buffer in bytes.
    137      */
    138     uint32_t getSize() const {
    139         return mWidth * mHeight * formatSize(mFormat);
    140     }
    141 
    142     /**
    143      * Returns the number of bytes per pixel in the specified format.
    144      *
    145      * Supported formats:
    146      *      GL_ALPHA
    147      *      GL_RGBA
    148      */
    149     static uint32_t formatSize(GLenum format) {
    150         switch (format) {
    151             case GL_ALPHA:
    152                 return 1;
    153             case GL_RGBA:
    154                 return 4;
    155         }
    156         return 0;
    157     }
    158 
    159 protected:
    160     /**
    161      * Creates a new render buffer in the specified format and dimensions.
    162      * The format must be GL_ALPHA or GL_RGBA.
    163      */
    164     PixelBuffer(GLenum format, uint32_t width, uint32_t height):
    165             mFormat(format), mWidth(width), mHeight(height), mAccessMode(kAccessMode_None) {
    166     }
    167 
    168     GLenum mFormat;
    169 
    170     uint32_t mWidth;
    171     uint32_t mHeight;
    172 
    173     AccessMode mAccessMode;
    174 
    175 }; // class PixelBuffer
    176 
    177 }; // namespace uirenderer
    178 }; // namespace android
    179 
    180 #endif // ANDROID_HWUI_PIXEL_BUFFER_H
    181