1 // Copyright (C) 2016 The Android Open Source Project 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 #pragma once 15 16 #include "RenderChannel.h" 17 #include "render_api_platform_types.h" 18 #include "base/Stream.h" 19 #include "base/ring_buffer.h" 20 #include "host-common/address_space_graphics_types.h" 21 #include "virtio_gpu_ops.h" 22 #include "snapshot/common.h" 23 24 #include <functional> 25 #include <memory> 26 #include <string> 27 28 namespace android_studio { 29 class EmulatorGLESUsages; 30 } 31 32 namespace emugl { 33 34 // Renderer - an object that manages a single OpenGL window used for drawing 35 // and is able to create individual render channels for that window. 36 // 37 class Renderer { 38 public: 39 // createRenderChannel - create a separate channel for the rendering data. 40 // This call instantiates a new object that waits for the serialized data 41 // from the guest, deserializes it, executes the passed GL commands and 42 // returns the results back. 43 // |loadStream| - if not NULL, RenderChannel uses it to load saved state 44 // asynchronously on its own thread. |loadStream| can be used right after 45 // the call as all the required data is copied here synchronously. 46 virtual RenderChannelPtr createRenderChannel( 47 android::base::Stream* loadStream = nullptr) = 0; 48 49 // analog of createRenderChannel, but for the address space graphics device 50 virtual void* addressSpaceGraphicsConsumerCreate( 51 struct asg_context, 52 android::base::Stream* loadStream, 53 android::emulation::asg::ConsumerCallbacks) = 0; 54 virtual void addressSpaceGraphicsConsumerDestroy(void*) = 0; 55 virtual void addressSpaceGraphicsConsumerPreSave(void* consumer) = 0; 56 virtual void addressSpaceGraphicsConsumerSave(void* consumer, android::base::Stream* stream) = 0; 57 virtual void addressSpaceGraphicsConsumerPostSave(void* consumer) = 0; 58 virtual void addressSpaceGraphicsConsumerRegisterPostLoadRenderThread(void* consumer) = 0; 59 60 // getHardwareStrings - describe the GPU hardware and driver. 61 // The underlying GL's vendor/renderer/version strings are returned to the 62 // caller. 63 struct HardwareStrings { 64 std::string vendor; 65 std::string renderer; 66 std::string version; 67 }; 68 virtual HardwareStrings getHardwareStrings() = 0; 69 70 // A per-frame callback can be registered with setPostCallback(); to remove 71 // it pass an empty callback. While a callback is registered, the renderer 72 // will call it just before each new frame is displayed, providing a copy of 73 // the framebuffer contents. 74 // 75 // The callback will be called from one of the renderer's threads, so will 76 // probably need synchronization on any data structures it modifies. The 77 // pixels buffer may be overwritten as soon as the callback returns; it 78 // doesn't need to be synchronized, but if the callback needs the pixels 79 // afterwards it must copy them. 80 // 81 // The pixels buffer is intentionally not const: the callback may modify the 82 // data without copying to another buffer if it wants, e.g. in-place RGBA to 83 // RGB conversion, or in-place y-inversion. 84 // 85 // Parameters are: 86 // displayId Default is 0. Can also be 1 to 10 if multi display 87 // configured. 88 // width, height Dimensions of the image, in pixels. Rows are tightly 89 // packed; there is no inter-row padding. 90 // ydir Indicates row order: 1 means top-to-bottom order, -1 91 // means bottom-to-top order. 92 // format, type Format and type GL enums, as used in glTexImage2D() or 93 // glReadPixels(), describing the pixel format. 94 // pixels The framebuffer image. 95 // 96 // In the first implementation, ydir is always -1 (bottom to top), format 97 // and type are always GL_RGBA and GL_UNSIGNED_BYTE, and the width and 98 // height will always be the same as the ones used to create the renderer. 99 using OnPostCallback = void (*)(void* context, 100 uint32_t displayId, 101 int width, 102 int height, 103 int ydir, 104 int format, 105 int type, 106 unsigned char* pixels); 107 virtual void setPostCallback(OnPostCallback onPost, 108 void* context, 109 bool useBgraReadback, 110 uint32_t displayId) = 0; 111 112 // Async readback API 113 virtual bool asyncReadbackSupported() = 0; 114 115 // Separate callback to get RGBA Pixels in async readback mode. 116 using ReadPixelsCallback = void (*)(void* pixels, uint32_t bytes, uint32_t displayId); 117 virtual ReadPixelsCallback getReadPixelsCallback() = 0; 118 119 using FlushReadPixelPipeline = void(*)(int displayId); 120 // Flushes the pipeline by duplicating the last frame and informing 121 // the async callback that a new frame is available if no reads are 122 // active 123 virtual FlushReadPixelPipeline getFlushReadPixelPipeline() = 0; 124 125 126 // showOpenGLSubwindow - 127 // Create or modify a native subwindow which is a child of 'window' 128 // to be used for framebuffer display. If a subwindow already exists, 129 // its properties will be updated to match the given parameters. 130 // wx,wy is the top left corner of the rendering subwindow. 131 // ww,wh are the dimensions of the rendering subwindow. 132 // fbw,fbh are the dimensions of the underlying guest framebuffer. 133 // dpr is the device pixel ratio, which is needed for higher density 134 // displays like retina. 135 // zRot is the rotation to apply on the framebuffer display image. 136 // 137 // Return true on success, false on failure, which can happen when using 138 // a software-only renderer like OSMesa. In this case, the client should 139 // call setPostCallback to get the content of each new frame when it is 140 // posted, and will be responsible for displaying it. 141 virtual bool showOpenGLSubwindow(FBNativeWindowType window, 142 int wx, 143 int wy, 144 int ww, 145 int wh, 146 int fbw, 147 int fbh, 148 float dpr, 149 float zRot, 150 bool deleteExisting, 151 bool hideWindow) = 0; 152 153 // destroyOpenGLSubwindow - 154 // destroys the created native subwindow. Once destroyed, 155 // Framebuffer content will not be visible until a new 156 // subwindow will be created. 157 virtual bool destroyOpenGLSubwindow() = 0; 158 159 // setOpenGLDisplayRotation - 160 // set the framebuffer display image rotation in units 161 // of degrees around the z axis 162 virtual void setOpenGLDisplayRotation(float zRot) = 0; 163 164 // setOpenGLDisplayTranslation 165 // change what coordinate of the guest framebuffer will be displayed at 166 // the corner of the GPU sub-window. Specifically, |px| and |py| = 0 167 // means 168 // align the bottom-left of the framebuffer with the bottom-left of the 169 // sub-window, and |px| and |py| = 1 means align the top right of the 170 // framebuffer with the top right of the sub-window. Intermediate values 171 // interpolate between these states. 172 virtual void setOpenGLDisplayTranslation(float px, float py) = 0; 173 174 // repaintOpenGLDisplay - 175 // causes the OpenGL subwindow to get repainted with the 176 // latest framebuffer content. 177 virtual void repaintOpenGLDisplay() = 0; 178 179 // hasGuestPostedAFrame / resetGuestPostedAFrame - 180 // for liveness checking; queries whether or not the guest 181 // has successfully issued a framebuffer post to the emulator, 182 // and a method to reset that state. 183 virtual bool hasGuestPostedAFrame() = 0; 184 virtual void resetGuestPostedAFrame() = 0; 185 186 // setScreenMask - 187 // provide the image that should be overlayed on the 188 // device screen to mask that screen 189 virtual void setScreenMask(int width, int height, const unsigned char* rgbaData) = 0; 190 191 // setMultiDisplay 192 // add/modify/del multi-display window 193 virtual void setMultiDisplay(uint32_t id, 194 int32_t x, 195 int32_t y, 196 uint32_t w, 197 uint32_t h, 198 uint32_t dpi, 199 bool add) = 0; 200 // setMultiDisplayColorBuffer 201 // bind ColorBuffer to the display 202 virtual void setMultiDisplayColorBuffer(uint32_t id, uint32_t cb) = 0; 203 204 // cleanupProcGLObjects - 205 // clean up all per-process resources when guest process exits (or is 206 // killed). Such resources include color buffer handles and EglImage handles. 207 virtual void cleanupProcGLObjects(uint64_t puid) = 0; 208 209 // Wait for cleanupProcGLObjects to finish. 210 virtual void waitForProcessCleanup() = 0; 211 212 virtual struct AndroidVirtioGpuOps* getVirtioGpuOps(void) = 0; 213 214 // Stops all channels and render threads. The renderer cannot be used after 215 // stopped. 216 virtual void stop(bool wait) = 0; 217 218 // Waits for all channels to finish and deletes all render threads. 219 // The renderer can still be used after finish(). 220 virtual void finish() = 0; 221 222 // Pauses all channels to prepare for snapshot saving. 223 virtual void pauseAllPreSave() = 0; 224 225 // Resumes all channels after snapshot saving or loading. 226 virtual void resumeAll() = 0; 227 228 virtual void save(android::base::Stream* stream, 229 const android::snapshot::ITextureSaverPtr& textureSaver) = 0; 230 virtual bool load(android::base::Stream* stream, 231 const android::snapshot::ITextureLoaderPtr& textureLoader) = 0; 232 // Fill GLES usage protobuf 233 virtual void fillGLESUsages(android_studio::EmulatorGLESUsages*) = 0; 234 virtual void getScreenshot(unsigned int nChannels, unsigned int* width, 235 unsigned int* height, std::vector<unsigned char>& pixels, int displayId = 0, 236 int desiredWidth = 0, int desiredHeight = 0, 237 int desiredRotation = 0) = 0; 238 virtual void snapshotOperationCallback( 239 int snapshotterOp, 240 int snapshotterStage) = 0; 241 242 protected: 243 ~Renderer() = default; 244 }; 245 246 using RendererPtr = std::shared_ptr<Renderer>; 247 248 } // namespace emugl 249