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