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 ~PixelBuffer()70 virtual ~PixelBuffer() { 71 } 72 73 /** 74 * Returns the format of this render buffer. 75 */ getFormat()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 */ getAccessMode()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 */ upload(uint32_t x,uint32_t y,uint32_t width,uint32_t height)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 */ getWidth()137 uint32_t getWidth() const { 138 return mWidth; 139 } 140 141 /** 142 * Returns the height of the render buffer in pixels. 143 */ getHeight()144 uint32_t getHeight() const { 145 return mHeight; 146 } 147 148 /** 149 * Returns the size of this pixel buffer in bytes. 150 */ getSize()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 */ getOffset(uint32_t x,uint32_t y)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 */ formatSize(GLenum format)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 */ formatAlphaOffset(GLenum format)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 */ PixelBuffer(GLenum format,uint32_t width,uint32_t height)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