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 AMBER_AMBER_H_
16#define AMBER_AMBER_H_
17
18#include <stdint.h>
19
20#include <map>
21#include <string>
22#include <vector>
23
24#include "amber/recipe.h"
25#include "amber/result.h"
26#include "amber/value.h"
27
28namespace amber {
29
30/// The shader map is a map from the name of a shader to the spirv-binary
31/// which is the compiled representation of that named shader.
32typedef std::map<std::string, std::vector<uint32_t> > ShaderMap;
33
34enum EngineType {
35  /// Use the Vulkan backend, if available
36  kEngineTypeVulkan = 0,
37  /// Use the Dawn backend, if available
38  kEngineTypeDawn,
39};
40
41enum class ExecutionType {
42  /// Execute as normal.
43  kExecute = 0,
44  /// Only create the pipelines and then exit.
45  kPipelineCreateOnly
46};
47
48/// Override point of engines to add their own configuration.
49struct EngineConfig {
50  virtual ~EngineConfig();
51};
52
53/// Stores information for a buffer.
54struct BufferInfo {
55  BufferInfo();
56  BufferInfo(const BufferInfo&);
57  ~BufferInfo();
58
59  BufferInfo& operator=(const BufferInfo&);
60
61  /// Determines if this is an image buffer.
62  bool is_image_buffer;
63  /// Holds the buffer name
64  std::string buffer_name;
65  /// Holds the buffer width
66  uint32_t width;
67  /// Holds the buffer height
68  uint32_t height;
69  /// Contains the buffer internal data
70  std::vector<Value> values;
71};
72
73/// Types of source file to load buffer data from.
74enum class BufferDataFileType : int8_t {
75  /// Unknown file type
76  kUnknown = -1,
77  /// A text file
78  kText = 0,
79  /// A binary file
80  kBinary,
81  /// A PNG file
82  kPng
83};
84
85/// Delegate class for various hook functions
86class Delegate {
87 public:
88  virtual ~Delegate();
89
90  /// Log the given message
91  virtual void Log(const std::string& message) = 0;
92  /// Tells whether to log the graphics API calls
93  virtual bool LogGraphicsCalls() const = 0;
94  /// Tells whether to log the duration of graphics API calls
95  virtual bool LogGraphicsCallsTime() const = 0;
96  /// Returns the current timestamp in nanoseconds
97  virtual uint64_t GetTimestampNs() const = 0;
98  /// Tells whether to log each test as it's executed
99  virtual bool LogExecuteCalls() const = 0;
100  /// Loads buffer data from a file
101  virtual amber::Result LoadBufferData(const std::string file_name,
102                                       BufferDataFileType file_type,
103                                       amber::BufferInfo* buffer) const = 0;
104};
105
106/// Stores configuration options for Amber.
107struct Options {
108  Options();
109  ~Options();
110
111  /// Sets the engine to be created. Default Vulkan.
112  EngineType engine;
113  /// Holds engine specific configuration. Ownership stays with the caller.
114  EngineConfig* config;
115  /// The SPIR-V environment to target.
116  /// E.g. "spv1.0", "spv1.3", "vulkan1.0", "vulkan1.1spv1.4".
117  /// If a Vulkan environment, uses the highest version of SPIR-V required
118  /// to be supported by that Vulkan environment.  For SPIR-V 1.4 in
119  /// Vulkan, use "vulkan1.1spv1.4".
120  /// If a SPIR-V environment is specified, assume the lowest version
121  /// of Vulkan that requires support for that version of SPIR-V.
122  /// Shader compilers may limit the list of supported environments.
123  /// If empty, a default of "spv1.0" is used.
124  std::string spv_env;
125  /// Lists the buffers to extract at the end of the execution
126  std::vector<BufferInfo> extractions;
127  /// The type of execution. For example, execute as normal or just create the
128  /// piplines and exit.
129  ExecutionType execution_type;
130  /// If true, disables SPIR-V validation. If false, SPIR-V shaders will be
131  /// validated using the Validator component (spirv-val) from SPIRV-Tools.
132  bool disable_spirv_validation;
133};
134
135/// Main interface to the Amber environment.
136class Amber {
137 public:
138  explicit Amber(Delegate* delegate);
139  ~Amber();
140
141  /// Parse the given |data| into the |recipe|.
142  amber::Result Parse(const std::string& data, amber::Recipe* recipe);
143
144  /// Determines whether the engine supports all features required by the
145  /// |recipe|. Modifies the |recipe| by applying some of the |opts| to the
146  /// recipe's internal state.
147  amber::Result AreAllRequirementsSupported(const amber::Recipe* recipe,
148                                            Options* opts);
149
150  /// Executes the given |recipe| with the provided |opts|. Returns a
151  /// |Result| which indicates if the execution succeded. Modifies the
152  /// |recipe| by applying some of the |opts| to the recipe's internal
153  /// state.
154  amber::Result Execute(const amber::Recipe* recipe, Options* opts);
155
156  /// Executes the given |recipe| with the provided |opts|. Will use
157  /// |shader_map| to lookup shader data before attempting to compile the
158  /// shader if possible.
159  amber::Result ExecuteWithShaderData(const amber::Recipe* recipe,
160                                      Options* opts,
161                                      const ShaderMap& shader_data);
162
163  /// Returns the delegate object.
164  Delegate* GetDelegate() const { return delegate_; }
165
166 private:
167  Delegate* delegate_;
168};
169
170}  // namespace amber
171
172#endif  // AMBER_AMBER_H_
173