1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 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 16 #ifndef API_RENDER_DEVICE_IDEVICE_H 17 #define API_RENDER_DEVICE_IDEVICE_H 18 19 #include <cstdint> 20 21 #include <render/device/gpu_resource_desc.h> 22 #include <render/device/pipeline_state_desc.h> 23 #include <render/namespace.h> 24 25 RENDER_BEGIN_NAMESPACE() 26 class IGpuResourceManager; 27 class IShaderManager; 28 29 struct BackendExtra {}; 30 struct RenderBackendRecordingState {}; 31 32 /** Device configuration flag bits */ 33 enum DeviceConfigurationFlagBits { 34 /** Enable pipeline caching */ 35 CORE_DEVICE_CONFIGURATION_PIPELINE_CACHE_BIT = 1 << 0, 36 }; 37 38 /** Swapchain flag bits */ 39 enum SwapchainFlagBits { 40 /** Color buffer */ 41 CORE_SWAPCHAIN_COLOR_BUFFER_BIT = 0x00000001, 42 /** Depth buffer */ 43 CORE_SWAPCHAIN_DEPTH_BUFFER_BIT = 0x00000002, 44 /** Enable v-sync */ 45 CORE_SWAPCHAIN_VSYNC_BIT = 0x00000004, 46 /** Hint to prefer sRGB format */ 47 CORE_SWAPCHAIN_SRGB_BIT = 0x00000008, 48 }; 49 /** Container for swapchain flag bits */ 50 using SwapchainFlags = uint32_t; 51 52 /** Swapchain create info */ 53 struct SwapchainCreateInfo { 54 /** Surface handle */ 55 uint64_t surfaceHandle { 0 }; 56 /** Swapchain flags */ 57 SwapchainFlags swapchainFlags { SwapchainFlagBits::CORE_SWAPCHAIN_COLOR_BUFFER_BIT | 58 SwapchainFlagBits::CORE_SWAPCHAIN_VSYNC_BIT | 59 SwapchainFlagBits::CORE_SWAPCHAIN_SRGB_BIT }; 60 /** Needed image usage flags for swapchain color image. Checked against supported */ 61 ImageUsageFlags imageUsageFlags { ImageUsageFlagBits::CORE_IMAGE_USAGE_COLOR_ATTACHMENT_BIT }; 62 63 struct SwapchainWindow { 64 /** Platform window pointer */ 65 uintptr_t window { 0 }; 66 /** Platform instance (hInstance, connection, display) */ 67 uintptr_t instance { 0 }; 68 }; 69 /** Window handles. Creates surface automatically. 70 * NOTE: do not create surface for surfaceHandle if the window and instance is provided 71 */ 72 SwapchainWindow window; 73 }; 74 75 struct DeviceConfiguration { 76 /** Maps to buffering count e.g. coherent gpu buffers and command buffers (vulkan) 77 * default value is 3, supported values depends from the backend. 78 * Should always be bigger or equal to swapchain count. Waits earlier in the frame. 79 */ 80 uint32_t bufferingCount { 3u }; 81 /** Maps to desired swapchain count default value is 3, 82 * and supported values depend from the backend. 83 */ 84 uint32_t swapchainImageCount { 3u }; 85 86 /** 87 * Integrated devices (mobile gpus, integrated desktop chips) expose all memory pools with host visible flags. 88 * If all pools have requiredIntegratedMemoryFlags then this optimization will be enabled and 89 * staging buffers are not used for this data. The data is directly mapped once for writing. 90 * Set to zero (0u) to disable all staging optimizations. 91 */ 92 uint32_t requiredIntegratedMemoryFlags { CORE_MEMORY_PROPERTY_DEVICE_LOCAL_BIT | 93 CORE_MEMORY_PROPERTY_HOST_VISIBLE_BIT }; 94 95 /** Additional options for device creation. 96 */ 97 uint32_t configurationFlags { CORE_DEVICE_CONFIGURATION_PIPELINE_CACHE_BIT }; 98 }; 99 100 /** Device backend type */ 101 enum class DeviceBackendType { 102 /** Vulkan backend */ 103 VULKAN, 104 /** GLES backend */ 105 OPENGLES, 106 /** OpenGL backend */ 107 OPENGL 108 }; 109 110 /** @ingroup group_idevice */ 111 /** Device create info */ 112 struct DeviceCreateInfo { 113 /** Backend type to be created */ 114 DeviceBackendType backendType { DeviceBackendType::VULKAN }; 115 /** Device configuration */ 116 DeviceConfiguration deviceConfiguration; 117 /** Backend configuration pointer */ 118 const BackendExtra* backendConfiguration { nullptr }; 119 }; 120 121 /** Common device properties for various features */ 122 struct CommonDeviceProperties { 123 /** Fragment shading rate properties */ 124 FragmentShadingRateProperties fragmentShadingRateProperties; 125 }; 126 127 /** @ingroup group_gfx_ilowleveldevice */ 128 /** ILowLevelDevice, to provide low-level access to platform device and resources. */ 129 class ILowLevelDevice { 130 public: 131 /** Returns backend type */ 132 virtual DeviceBackendType GetBackendType() const = 0; 133 134 protected: 135 ILowLevelDevice() = default; 136 virtual ~ILowLevelDevice() = default; 137 }; 138 139 /** @ingroup group_idevice */ 140 struct DevicePlatformData {}; 141 142 /** Settings which can be changed after device has been created. */ 143 struct BackendConfig {}; 144 145 /** @ingroup group_idevice 146 * IDevice interface for accessing device. 147 * Not internally synchronized and therefore Create And Destroy -methods 148 * need to be called from the rendering thread. 149 * NOTE: Even though CreateSwapchainHandle returns a reference counted image handle, 150 * one needs to explicitly destroy the swapchain with DestroySwapchain(handle) 151 */ 152 class IDevice { 153 public: 154 /** Create a swapchain for graphics API use. 155 * @param swapchainCreateInfo Swapchain creation info. 156 */ 157 virtual void CreateSwapchain(const SwapchainCreateInfo& swapchainCreateInfo) = 0; 158 159 /** Destroys swapchain 160 */ 161 virtual void DestroySwapchain() = 0; 162 163 /** Create a swapchain for graphics API use. Prefer using this method. 164 * Replace handle to re-use the same shallow handle throughout the Render. 165 * Add global unique image name to get global access to the resource. 166 * @param swapchainCreateInfo Swapchain creation info. 167 * @param replacedHandle Handle to be used as a shallow render handle for swapchain images. 168 * @param name Optional unique global name for the image. 169 */ 170 virtual RenderHandleReference CreateSwapchainHandle(const SwapchainCreateInfo& swapchainCreateInfo, 171 const RenderHandleReference& replacedHandle, const BASE_NS::string_view name) = 0; 172 173 /** Create a swapchain for graphics API use. 174 * @param swapchainCreateInfo Swapchain creation info. 175 */ 176 virtual RenderHandleReference CreateSwapchainHandle(const SwapchainCreateInfo& swapchainCreateInfo) = 0; 177 178 /** Destroys swapchain 179 */ 180 virtual void DestroySwapchain(const RenderHandleReference& handle) = 0; 181 182 /** Returns backend type (vulkan, gles, etc) */ 183 virtual DeviceBackendType GetBackendType() const = 0; 184 185 /** Returns device platform data which needs to be cast for correct device. */ 186 virtual const DevicePlatformData& GetPlatformData() const = 0; 187 188 /** Get GPU resource manager interface. */ 189 virtual IGpuResourceManager& GetGpuResourceManager() const = 0; 190 /** Get shader manager interface. */ 191 virtual IShaderManager& GetShaderManager() const = 0; 192 193 /** Returns supported flags for given format. */ 194 virtual FormatProperties GetFormatProperties(const BASE_NS::Format format) const = 0; 195 196 /** Returns common device properties */ 197 virtual const CommonDeviceProperties& GetCommonDeviceProperties() const = 0; 198 199 /** Returns acceleration structure build sizes. Only a single geometry data should be valid. 200 * @param geometryInfo Build geometry info for size calculations. 201 * @param triangles Build geometry info for size calculations. 202 * @param aabb Build geometry info for size calculations. 203 * @param instances Build geometry info for size calculations. 204 */ 205 virtual AccelerationStructureBuildSizes GetAccelerationStructureBuildSizes( 206 const AccelerationStructureBuildGeometryInfo& geometry, 207 BASE_NS::array_view<const AccelerationStructureGeometryTrianglesInfo> triangles, 208 BASE_NS::array_view<const AccelerationStructureGeometryAabbsInfo> aabbs, 209 BASE_NS::array_view<const AccelerationStructureGeometryInstancesInfo> instances) const = 0; 210 211 /** Get frame count. */ 212 virtual uint64_t GetFrameCount() const = 0; 213 214 /** Wait for the GPU to become idle. 215 * Needs to be called from render thread where renderFrame is called. 216 * 217 * This is a hazardous method and should only be called with extreme caution. 218 * Do not call this method per frame. 219 */ 220 virtual void WaitForIdle() = 0; 221 222 /** Get low level device interface. Needs to be cast to correct ILowLevelDeviceXX based on backend type. */ 223 virtual ILowLevelDevice& GetLowLevelDevice() const = 0; 224 225 /** Update backend configuration. 226 * @param config Backend type specific settings. 227 */ 228 virtual void SetBackendConfig(const BackendConfig& config) = 0; 229 230 /** Get device configuration. 231 * The device configuration is updated after creation, i.e. the config might not match the device creation struct. 232 * @return Returns device configuration. 233 */ 234 virtual DeviceConfiguration GetDeviceConfiguration() const = 0; 235 236 protected: 237 IDevice() = default; 238 virtual ~IDevice() = default; 239 }; 240 241 /** @ingroup group_idevice */ 242 struct GpuBufferPlatformData {}; 243 struct GpuImagePlatformData {}; 244 struct GpuSamplerPlatformData {}; 245 struct GpuAccelerationStructurePlatformData {}; 246 RENDER_END_NAMESPACE() 247 248 #endif // API_RENDER_DEVICE_IDEVICE_H 249