1 // Copyright 2018 The Amber Authors. 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 15 #ifndef SRC_ENGINE_H_ 16 #define SRC_ENGINE_H_ 17 18 #include <memory> 19 #include <string> 20 #include <utility> 21 #include <vector> 22 23 #include "amber/amber.h" 24 #include "amber/result.h" 25 #include "src/buffer.h" 26 #include "src/command.h" 27 #include "src/format.h" 28 #include "src/pipeline.h" 29 30 namespace amber { 31 32 class VirtualFileStore; 33 34 /// EngineData stores information used during engine execution. 35 struct EngineData { 36 /// The timeout to use for fences, in milliseconds. 37 uint32_t fence_timeout_ms = 10000; 38 }; 39 40 /// Abstract class which describes a backing engine for Amber. 41 /// 42 /// The engine class has a defined lifecycle. 43 /// 1. The engine is created through Engine::Create. 44 /// 2. Engine::Initialize is called to provide the engine with the configured 45 /// graphics device. 46 /// 3. Engine::CreatePipeline is called for each pipeline. The pipelines are 47 /// fully specified at this point and include: 48 /// * All compiled shader binaries 49 /// * Vertex, Index, Storage, Uniform, Push Constant buffers 50 /// * Colour attachment, and depth/stencil attachment buffers. 51 /// * Extra engine data. 52 /// The buffers all may have default values to be loaded into the device. 53 /// 4. Engine::Do* is called for each command. 54 /// Note, it is assumed that the amber::Buffers are updated at the end of 55 /// each Do* command and can be used immediately for comparisons. 56 /// 5. Engine destructor is called. 57 class Engine { 58 public: 59 /// Debugger is the interface to the engine's shader debugger. 60 class Debugger : public debug::Events { 61 public: 62 ~Debugger() override; 63 64 /// Flush waits for all the debugger commands issued to complete, and 65 /// returns a Result that includes any debugger test failure. 66 virtual Result Flush() = 0; 67 }; 68 69 /// Creates a new engine of the requested |type|. 70 static std::unique_ptr<Engine> Create(EngineType type); 71 72 virtual ~Engine(); 73 74 /// Initialize the engine with the provided config. The config is _not_ owned 75 /// by the engine and will not be destroyed. The |features| and |extensions| 76 /// are for validation purposes only. If possible the engine should verify 77 /// that the constraints in |features| and |extensions| are valid and fail 78 /// otherwise. 79 virtual Result Initialize( 80 EngineConfig* config, 81 Delegate* delegate, 82 const std::vector<std::string>& features, 83 const std::vector<std::string>& instance_extensions, 84 const std::vector<std::string>& device_extensions) = 0; 85 86 /// Create graphics pipeline. 87 virtual Result CreatePipeline(Pipeline* pipeline) = 0; 88 89 /// Execute the clear color command 90 virtual Result DoClearColor(const ClearColorCommand* cmd) = 0; 91 92 /// Execute the clear stencil command 93 virtual Result DoClearStencil(const ClearStencilCommand* cmd) = 0; 94 95 /// Execute the clear depth command 96 virtual Result DoClearDepth(const ClearDepthCommand* cmd) = 0; 97 98 /// Execute the clear command 99 virtual Result DoClear(const ClearCommand* cmd) = 0; 100 101 /// Execute the draw rect command 102 virtual Result DoDrawRect(const DrawRectCommand* cmd) = 0; 103 104 /// Execute the draw grid command 105 virtual Result DoDrawGrid(const DrawGridCommand* cmd) = 0; 106 107 /// Execute the draw arrays command 108 virtual Result DoDrawArrays(const DrawArraysCommand* cmd) = 0; 109 110 /// Execute the compute command 111 virtual Result DoCompute(const ComputeCommand* cmd) = 0; 112 113 /// Execute the entry point command 114 virtual Result DoEntryPoint(const EntryPointCommand* cmd) = 0; 115 116 /// Execute the patch command 117 virtual Result DoPatchParameterVertices( 118 const PatchParameterVerticesCommand* cmd) = 0; 119 120 /// Execute the buffer command. 121 /// This declares an Amber buffer to be bound to a descriptor. 122 /// This covers both Vulkan buffers and images. 123 virtual Result DoBuffer(const BufferCommand* cmd) = 0; 124 125 /// GetDebugger returns the shader debugger from the engine. 126 /// If the engine does not support a shader debugger then the Result will be a 127 /// failure. 128 virtual std::pair<Debugger*, Result> GetDebugger(VirtualFileStore*) = 0; 129 130 /// Sets the engine data to use. SetEngineData(const EngineData & data)131 void SetEngineData(const EngineData& data) { engine_data_ = data; } 132 133 protected: 134 Engine(); 135 136 /// Retrieves the engine data. GetEngineData()137 const EngineData& GetEngineData() const { return engine_data_; } 138 139 private: 140 EngineData engine_data_; 141 }; 142 143 } // namespace amber 144 145 #endif // SRC_ENGINE_H_ 146