1 // Copyright 2018 The Dawn 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 DAWNNATIVE_DAWNNATIVE_H_ 16 #define DAWNNATIVE_DAWNNATIVE_H_ 17 18 #include <dawn/dawn_proc_table.h> 19 #include <dawn/webgpu.h> 20 #include <dawn_native/dawn_native_export.h> 21 22 #include <string> 23 #include <vector> 24 25 namespace dawn_platform { 26 class Platform; 27 } // namespace dawn_platform 28 29 namespace wgpu { 30 struct AdapterProperties; 31 } 32 33 namespace dawn_native { 34 35 // DEPRECATED: use WGPUAdapterProperties instead. 36 struct PCIInfo { 37 uint32_t deviceId = 0; 38 uint32_t vendorId = 0; 39 std::string name; 40 }; 41 42 // DEPRECATED: use WGPUBackendType instead. 43 enum class BackendType { 44 D3D12, 45 Metal, 46 Null, 47 OpenGL, 48 OpenGLES, 49 Vulkan, 50 }; 51 52 // DEPRECATED: use WGPUAdapterType instead. 53 enum class DeviceType { 54 DiscreteGPU, 55 IntegratedGPU, 56 CPU, 57 Unknown, 58 }; 59 60 class InstanceBase; 61 class AdapterBase; 62 63 // An optional parameter of Adapter::CreateDevice() to send additional information when creating 64 // a Device. For example, we can use it to enable a workaround, optimization or feature. 65 struct DAWN_NATIVE_EXPORT DawnDeviceDescriptor { 66 std::vector<const char*> requiredFeatures; 67 std::vector<const char*> forceEnabledToggles; 68 std::vector<const char*> forceDisabledToggles; 69 70 const WGPURequiredLimits* requiredLimits = nullptr; 71 }; 72 73 // TODO(crbug.com/dawn/160): Remove when embedders of Dawn are updated to use 74 // DawnDeviceDescriptor. 75 using DeviceDescriptor = DawnDeviceDescriptor; 76 77 // A struct to record the information of a toggle. A toggle is a code path in Dawn device that 78 // can be manually configured to run or not outside Dawn, including workarounds, special 79 // features and optimizations. 80 struct ToggleInfo { 81 const char* name; 82 const char* description; 83 const char* url; 84 }; 85 86 // A struct to record the information of a feature. A feature is a GPU feature that is not 87 // required to be supported by all Dawn backends and can only be used when it is enabled on the 88 // creation of device. 89 using FeatureInfo = ToggleInfo; 90 91 // An adapter is an object that represent on possibility of creating devices in the system. 92 // Most of the time it will represent a combination of a physical GPU and an API. Not that the 93 // same GPU can be represented by multiple adapters but on different APIs. 94 // 95 // The underlying Dawn adapter is owned by the Dawn instance so this class is not RAII but just 96 // a reference to an underlying adapter. 97 class DAWN_NATIVE_EXPORT Adapter { 98 public: 99 Adapter(); 100 Adapter(AdapterBase* impl); 101 ~Adapter(); 102 103 Adapter(const Adapter& other); 104 Adapter& operator=(const Adapter& other); 105 106 // DEPRECATED: use GetProperties instead. 107 BackendType GetBackendType() const; 108 DeviceType GetDeviceType() const; 109 const PCIInfo& GetPCIInfo() const; 110 111 // Essentially webgpu.h's wgpuAdapterGetProperties while we don't have WGPUAdapter in 112 // dawn.json 113 void GetProperties(wgpu::AdapterProperties* properties) const; 114 115 std::vector<const char*> GetSupportedExtensions() const; 116 std::vector<const char*> GetSupportedFeatures() const; 117 WGPUDeviceProperties GetAdapterProperties() const; 118 bool GetLimits(WGPUSupportedLimits* limits) const; 119 120 void SetUseTieredLimits(bool useTieredLimits); 121 122 // Check that the Adapter is able to support importing external images. This is necessary 123 // to implement the swapchain and interop APIs in Chromium. 124 bool SupportsExternalImages() const; 125 126 explicit operator bool() const; 127 128 // Create a device on this adapter, note that the interface will change to include at least 129 // a device descriptor and a pointer to backend specific options. 130 // On an error, nullptr is returned. 131 WGPUDevice CreateDevice(const DawnDeviceDescriptor* deviceDescriptor = nullptr); 132 133 void RequestDevice(const DawnDeviceDescriptor* descriptor, 134 WGPURequestDeviceCallback callback, 135 void* userdata); 136 137 // Reset the backend device object for testing purposes. 138 void ResetInternalDeviceForTesting(); 139 140 private: 141 AdapterBase* mImpl = nullptr; 142 }; 143 144 // Base class for options passed to Instance::DiscoverAdapters. 145 struct DAWN_NATIVE_EXPORT AdapterDiscoveryOptionsBase { 146 public: 147 const WGPUBackendType backendType; 148 149 protected: 150 AdapterDiscoveryOptionsBase(WGPUBackendType type); 151 }; 152 153 enum BackendValidationLevel { Full, Partial, Disabled }; 154 155 // Represents a connection to dawn_native and is used for dependency injection, discovering 156 // system adapters and injecting custom adapters (like a Swiftshader Vulkan adapter). 157 // 158 // This is an RAII class for Dawn instances and also controls the lifetime of all adapters 159 // for this instance. 160 class DAWN_NATIVE_EXPORT Instance { 161 public: 162 Instance(); 163 ~Instance(); 164 165 Instance(const Instance& other) = delete; 166 Instance& operator=(const Instance& other) = delete; 167 168 // Gather all adapters in the system that can be accessed with no special options. These 169 // adapters will later be returned by GetAdapters. 170 void DiscoverDefaultAdapters(); 171 172 // Adds adapters that can be discovered with the options provided (like a getProcAddress). 173 // The backend is chosen based on the type of the options used. Returns true on success. 174 bool DiscoverAdapters(const AdapterDiscoveryOptionsBase* options); 175 176 // Returns all the adapters that the instance knows about. 177 std::vector<Adapter> GetAdapters() const; 178 179 const ToggleInfo* GetToggleInfo(const char* toggleName); 180 181 // Enables backend validation layers 182 void EnableBackendValidation(bool enableBackendValidation); 183 void SetBackendValidationLevel(BackendValidationLevel validationLevel); 184 185 // Enable debug capture on Dawn startup 186 void EnableBeginCaptureOnStartup(bool beginCaptureOnStartup); 187 188 void SetPlatform(dawn_platform::Platform* platform); 189 190 // Returns the underlying WGPUInstance object. 191 WGPUInstance Get() const; 192 193 private: 194 InstanceBase* mImpl = nullptr; 195 }; 196 197 // Backend-agnostic API for dawn_native 198 DAWN_NATIVE_EXPORT const DawnProcTable& GetProcs(); 199 200 // Query the names of all the toggles that are enabled in device 201 DAWN_NATIVE_EXPORT std::vector<const char*> GetTogglesUsed(WGPUDevice device); 202 203 // Backdoor to get the number of lazy clears for testing 204 DAWN_NATIVE_EXPORT size_t GetLazyClearCountForTesting(WGPUDevice device); 205 206 // Backdoor to get the number of deprecation warnings for testing 207 DAWN_NATIVE_EXPORT size_t GetDeprecationWarningCountForTesting(WGPUDevice device); 208 209 // Query if texture has been initialized 210 DAWN_NATIVE_EXPORT bool IsTextureSubresourceInitialized( 211 WGPUTexture texture, 212 uint32_t baseMipLevel, 213 uint32_t levelCount, 214 uint32_t baseArrayLayer, 215 uint32_t layerCount, 216 WGPUTextureAspect aspect = WGPUTextureAspect_All); 217 218 // Backdoor to get the order of the ProcMap for testing 219 DAWN_NATIVE_EXPORT std::vector<const char*> GetProcMapNamesForTesting(); 220 221 DAWN_NATIVE_EXPORT bool DeviceTick(WGPUDevice device); 222 223 // ErrorInjector functions used for testing only. Defined in dawn_native/ErrorInjector.cpp 224 DAWN_NATIVE_EXPORT void EnableErrorInjector(); 225 DAWN_NATIVE_EXPORT void DisableErrorInjector(); 226 DAWN_NATIVE_EXPORT void ClearErrorInjector(); 227 DAWN_NATIVE_EXPORT uint64_t AcquireErrorInjectorCallCount(); 228 DAWN_NATIVE_EXPORT void InjectErrorAt(uint64_t index); 229 230 // The different types of external images 231 enum ExternalImageType { 232 OpaqueFD, 233 DmaBuf, 234 IOSurface, 235 DXGISharedHandle, 236 EGLImage, 237 }; 238 239 // Common properties of external images 240 struct DAWN_NATIVE_EXPORT ExternalImageDescriptor { 241 public: 242 const ExternalImageType type; 243 const WGPUTextureDescriptor* cTextureDescriptor; // Must match image creation params 244 bool isInitialized; // Whether the texture is initialized on import 245 246 protected: 247 ExternalImageDescriptor(ExternalImageType type); 248 }; 249 250 struct DAWN_NATIVE_EXPORT ExternalImageAccessDescriptor { 251 public: 252 bool isInitialized; // Whether the texture is initialized on import 253 WGPUTextureUsageFlags usage; 254 }; 255 256 struct DAWN_NATIVE_EXPORT ExternalImageExportInfo { 257 public: 258 const ExternalImageType type; 259 bool isInitialized; // Whether the texture is initialized after export 260 261 protected: 262 ExternalImageExportInfo(ExternalImageType type); 263 }; 264 265 DAWN_NATIVE_EXPORT const char* GetObjectLabelForTesting(void* objectHandle); 266 267 DAWN_NATIVE_EXPORT uint64_t GetAllocatedSizeForTesting(WGPUBuffer buffer); 268 269 DAWN_NATIVE_EXPORT bool BindGroupLayoutBindingsEqualForTesting(WGPUBindGroupLayout a, 270 WGPUBindGroupLayout b); 271 272 } // namespace dawn_native 273 274 #endif // DAWNNATIVE_DAWNNATIVE_H_ 275