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 protected: 179 /** 180 * Creates a new render buffer in the specified format and dimensions. 181 * The format must be GL_ALPHA or GL_RGBA. 182 */ 183 PixelBuffer(GLenum format, uint32_t width, uint32_t height): 184 mFormat(format), mWidth(width), mHeight(height), mAccessMode(kAccessMode_None) { 185 } 186 187 GLenum mFormat; 188 189 uint32_t mWidth; 190 uint32_t mHeight; 191 192 AccessMode mAccessMode; 193 194 }; // class PixelBuffer 195 196 }; // namespace uirenderer 197 }; // namespace android 198 199 #endif // ANDROID_HWUI_PIXEL_BUFFER_H 200
