1 #ifndef DALI_GRAPHICS_API_TYPES
2 #define DALI_GRAPHICS_API_TYPES
5 * Copyright (c) 2021 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
38 * @brief Structure describes 2D offset
47 * @brief Structure describes 2D dimensions
56 * @brief Structure describes 2D rectangle (offset, extent)
67 * @brief Structure represents area of viewport
75 float minDepth = 0.0f;
76 float maxDepth = 0.0f;
80 * @brief Describes vertex attribute input rate
82 enum class VertexInputRate
84 PER_VERTEX, ///< Attribute read per vertex
85 PER_INSTANCE ///< Attribute read per instance
89 * @brief Vertex input format
91 * When UNDEFINED, the reflection is used to determine what
92 * the actual format is.
94 enum class VertexInputFormat
108 * @brief Logic operators used by color blending state
109 * when logicOpEnable is set.
132 * @brief Blend factors
134 enum class BlendFactor
139 ONE_MINUS_SRC_COLOR = 3,
141 ONE_MINUS_DST_COLOR = 5,
143 ONE_MINUS_SRC_ALPHA = 7,
145 ONE_MINUS_DST_ALPHA = 9,
147 ONE_MINUS_CONSTANT_COLOR = 11,
149 ONE_MINUS_CONSTANT_ALPHA = 13,
150 SRC_ALPHA_SATURATE = 14,
152 ONE_MINUS_SRC1_COLOR = 16,
154 ONE_MINUS_SRC1_ALPHA = 18,
158 * @brief Blend operators
164 REVERSE_SUBTRACT = 2,
170 * @brief Compare operators
185 * @brief Stencil operators
200 * @brief Backface culling modes
211 * @brief Polygon drawing modes
213 enum class PolygonMode
221 * @brief Front face direction
230 * @brief Primitive geometry topology
232 enum class PrimitiveTopology
244 * @brief Sampler address ( wrapping ) mode
246 enum class SamplerAddressMode
256 * @brief Filtering mode
258 enum class SamplerFilter
267 enum class SamplerMipmapMode
275 * @brief Describes pipeline's color blend state
277 struct ColorBlendState
279 bool logicOpEnable = false;
280 LogicOp logicOp = {};
281 float blendConstants[4] = {0.0f, 0.0f, 0.0f, 0.0f};
282 bool blendEnable = false;
283 BlendFactor srcColorBlendFactor = BlendFactor::ZERO;
284 BlendFactor dstColorBlendFactor = BlendFactor::ZERO;
285 BlendOp colorBlendOp = {};
286 BlendFactor srcAlphaBlendFactor = BlendFactor::ZERO;
287 BlendFactor dstAlphaBlendFactor = BlendFactor::ZERO;
288 BlendOp alphaBlendOp = {};
289 uint32_t colorComponentWriteBits = {0u};
291 auto& SetLogicOpEnable(bool value)
293 logicOpEnable = value;
297 auto& SetLogicOp(LogicOp value)
303 auto& SetBlendConstants(float value[4])
305 std::copy(value, value + 4, blendConstants);
309 auto& SetBlendEnable(bool value)
315 auto& SetSrcColorBlendFactor(BlendFactor value)
317 srcColorBlendFactor = value;
321 auto& SetDstColorBlendFactor(BlendFactor value)
323 dstColorBlendFactor = value;
327 auto& SetColorBlendOp(BlendOp value)
329 colorBlendOp = value;
333 auto& SetSrcAlphaBlendFactor(BlendFactor value)
335 srcAlphaBlendFactor = value;
339 auto& SetDstAlphaBlendFactor(BlendFactor value)
341 dstAlphaBlendFactor = value;
345 auto& SetAlphaBlendOp(BlendOp value)
347 alphaBlendOp = value;
351 auto& SetColorComponentsWriteBits(uint32_t value)
353 colorComponentWriteBits = value;
359 * @brief Framebuffer state
361 struct FramebufferState
363 const Framebuffer* framebuffer{nullptr};
365 auto& SetFramebuffer(const Framebuffer& value)
367 framebuffer = &value;
373 * @brief Describes pipeline's viewport and scissor state
377 Viewport viewport{0.0, 0.0, 0.0, 0.0};
378 Rect2D scissor{0, 0, 0, 0};
379 bool scissorTestEnable{false};
381 auto& SetViewport(const Viewport& value)
387 auto& SetScissor(const Rect2D& value)
393 auto& SetScissorTestEnable(bool value)
395 scissorTestEnable = value;
401 * @brief Describes stencil operation state
403 struct StencilOpState
407 StencilOp depthFailOp{};
408 CompareOp compareOp{};
409 uint32_t compareMask{0u};
410 uint32_t writeMask{0u};
411 uint32_t reference{0u};
413 auto& SetFailOp(StencilOp value)
419 auto& SetPassOp(StencilOp value)
425 auto& SetDepthFailOp(StencilOp value)
431 auto& SetCompareOp(CompareOp value)
437 auto& SetCompareMask(uint32_t value)
443 auto& SetWriteMask(uint32_t value)
449 auto& SetReference(uint32_t value)
457 * @brief Describes pipeline's viewport and scissor state
459 struct DepthStencilState
461 bool depthTestEnable{false};
462 bool depthWriteEnable{false};
463 CompareOp depthCompareOp{};
465 bool stencilTestEnable{false};
466 StencilOpState front{};
467 StencilOpState back{};
469 auto& SetDepthTestEnable(bool value)
471 depthTestEnable = value;
475 auto& SetDepthWriteEnable(bool value)
477 depthWriteEnable = value;
481 auto& SetDepthCompareOp(CompareOp value)
483 depthCompareOp = value;
487 auto& SetFront(StencilOpState value)
493 auto& SetBack(StencilOpState value)
499 auto& SetStencilTestEnable(bool value)
501 stencilTestEnable = value;
507 * @brief Rasterization state descriptor
509 struct RasterizationState
512 PolygonMode polygonMode{};
513 FrontFace frontFace{};
515 auto& SetCullMode(CullMode value)
521 auto& SetPolygonMode(PolygonMode value)
527 auto& SetFrontFace(FrontFace value)
535 * @brief Input assembly state descriptor.
537 * Structure describes the topology for submitted
540 struct InputAssemblyState
542 PrimitiveTopology topology{};
543 bool primitiveRestartEnable{true};
545 auto& SetTopology(PrimitiveTopology value)
551 auto& SetPrimitiveRestartEnable(bool value)
553 primitiveRestartEnable = true;
559 * @brief Pipeline dynamic state bits
561 namespace PipelineDynamicStateBits
563 const uint32_t VIEWPORT_BIT = 1 << 0;
564 const uint32_t SCISSOR_BIT = 1 << 1;
565 const uint32_t LINE_WIDTH_BIT = 1 << 2;
566 const uint32_t DEPTH_BIAS_BIT = 1 << 3;
567 const uint32_t BLEND_CONSTANTS_BIT = 1 << 4;
568 const uint32_t DEPTH_BOUNDS_BIT = 1 << 5;
569 const uint32_t STENCIL_COMPARE_MASK_BIT = 1 << 6;
570 const uint32_t STENCIL_WRITE_MASK_BIT = 1 << 7;
571 const uint32_t STENCIL_REFERENCE_BIT = 1 << 8;
572 } // namespace PipelineDynamicStateBits
574 const uint32_t PIPELINE_DYNAMIC_STATE_COUNT(9u);
576 using PipelineDynamicStateMask = uint32_t;
579 * @brief Structure describes vertex input state of the pipeline.
580 * It specifies buffer binding and attribute format to be used.
582 struct VertexInputState
584 VertexInputState() = default;
587 * @brief Vertex buffer binding
591 Binding(uint32_t _stride, VertexInputRate _inputRate)
593 inputRate(_inputRate)
597 VertexInputRate inputRate;
601 * @brief Attribute description
605 Attribute(uint32_t _location, uint32_t _binding, uint32_t _offset, VertexInputFormat _format)
606 : location(_location),
616 VertexInputFormat format;
619 VertexInputState(std::vector<Binding> _bufferBindings, std::vector<Attribute> _attributes)
620 : bufferBindings(std::move(_bufferBindings)),
621 attributes(std::move(_attributes))
625 std::vector<Binding> bufferBindings{};
626 std::vector<Attribute> attributes{};
630 * @brief List of all possible formats
631 * Not all formats may be supported
636 // GLES compatible, luminance doesn't exist in Vulkan
642 R4G4B4A4_UNORM_PACK16,
643 B4G4R4A4_UNORM_PACK16,
646 R5G5B5A1_UNORM_PACK16,
647 B5G5R5A1_UNORM_PACK16,
648 A1R5G5B5_UNORM_PACK16,
691 A8B8G8R8_UNORM_PACK32,
692 A8B8G8R8_SNORM_PACK32,
693 A8B8G8R8_USCALED_PACK32,
694 A8B8G8R8_SSCALED_PACK32,
695 A8B8G8R8_UINT_PACK32,
696 A8B8G8R8_SINT_PACK32,
697 A8B8G8R8_SRGB_PACK32,
698 A2R10G10B10_UNORM_PACK32,
699 A2R10G10B10_SNORM_PACK32,
700 A2R10G10B10_USCALED_PACK32,
701 A2R10G10B10_SSCALED_PACK32,
702 A2R10G10B10_UINT_PACK32,
703 A2R10G10B10_SINT_PACK32,
704 A2B10G10R10_UNORM_PACK32,
705 A2B10G10R10_SNORM_PACK32,
706 A2B10G10R10_USCALED_PACK32,
707 A2B10G10R10_SSCALED_PACK32,
708 A2B10G10R10_UINT_PACK32,
709 A2B10G10R10_SINT_PACK32,
733 R16G16B16A16_USCALED,
734 R16G16B16A16_SSCALED,
762 B10G11R11_UFLOAT_PACK32,
763 E5B9G9R9_UFLOAT_PACK32,
773 BC1_RGBA_UNORM_BLOCK,
787 ETC2_R8G8B8_UNORM_BLOCK,
788 ETC2_R8G8B8_SRGB_BLOCK,
789 ETC2_R8G8B8A1_UNORM_BLOCK,
790 ETC2_R8G8B8A1_SRGB_BLOCK,
791 ETC2_R8G8B8A8_UNORM_BLOCK,
792 ETC2_R8G8B8A8_SRGB_BLOCK,
795 EAC_R11G11_UNORM_BLOCK,
796 EAC_R11G11_SNORM_BLOCK,
797 ASTC_4x4_UNORM_BLOCK,
799 ASTC_5x4_UNORM_BLOCK,
801 ASTC_5x5_UNORM_BLOCK,
803 ASTC_6x5_UNORM_BLOCK,
805 ASTC_6x6_UNORM_BLOCK,
807 ASTC_8x5_UNORM_BLOCK,
809 ASTC_8x6_UNORM_BLOCK,
811 ASTC_8x8_UNORM_BLOCK,
813 ASTC_10x5_UNORM_BLOCK,
814 ASTC_10x5_SRGB_BLOCK,
815 ASTC_10x6_UNORM_BLOCK,
816 ASTC_10x6_SRGB_BLOCK,
817 ASTC_10x8_UNORM_BLOCK,
818 ASTC_10x8_SRGB_BLOCK,
819 ASTC_10x10_UNORM_BLOCK,
820 ASTC_10x10_SRGB_BLOCK,
821 ASTC_12x10_UNORM_BLOCK,
822 ASTC_12x10_SRGB_BLOCK,
823 ASTC_12x12_UNORM_BLOCK,
824 ASTC_12x12_SRGB_BLOCK,
825 PVRTC1_2BPP_UNORM_BLOCK_IMG,
826 PVRTC1_4BPP_UNORM_BLOCK_IMG,
827 PVRTC2_2BPP_UNORM_BLOCK_IMG,
828 PVRTC2_4BPP_UNORM_BLOCK_IMG,
829 PVRTC1_2BPP_SRGB_BLOCK_IMG,
830 PVRTC1_4BPP_SRGB_BLOCK_IMG,
831 PVRTC2_2BPP_SRGB_BLOCK_IMG,
832 PVRTC2_4BPP_SRGB_BLOCK_IMG,
836 * @brief Flags specifying a buffer usage
838 enum class BufferUsage
840 TRANSFER_SRC = 1 << 0,
841 TRANSFER_DST = 1 << 1,
842 UNIFORM_TEXEL_BUFFER = 1 << 2,
843 STORAGE_TEXEL_BUFFER = 1 << 3,
844 UNIFORM_BUFFER = 1 << 4,
845 STORAGE_BUFFER = 1 << 5,
846 INDEX_BUFFER = 1 << 6,
847 VERTEX_BUFFER = 1 << 7,
848 INDIRECT_BUFFER = 1 << 8,
851 using BufferUsageFlags = uint32_t;
853 inline BufferUsageFlags operator|(BufferUsageFlags flags, BufferUsage usage)
855 flags |= static_cast<uint32_t>(usage);
860 * @brief The structure describes memory requirements of GPU resource (texture, buffer)
862 struct MemoryRequirements
868 using TextureUpdateFlags = uint32_t;
869 enum class TextureUpdateFlagBits
871 KEEP_SOURCE = 1 << 0,
875 * @brief Texture update info
877 * Describes the texture update to be executed by
878 * Controller::UpdateTextures()
880 struct TextureUpdateInfo
882 Texture* dstTexture{};
883 Offset2D dstOffset2D;
887 uint32_t srcReference{};
888 Extent2D srcExtent2D{};
889 uint32_t srcOffset{};
894 * @brief Texture update source info
896 * Describes the source of data (memory, buffer or another texture)
897 * to be used when updating textures using Controller::UpdateTextures().
899 struct TextureUpdateSourceInfo
927 * @brief Properties of texture
929 struct TextureProperties
931 Format format; ///< Texture format
932 Format format1; ///< Texture format (if emulated)
933 bool emulated; ///< Format is emulated (for example RGB as RGBA)
934 bool compressed; ///< Texture is compressed
935 bool packed; ///< Texture is packed
936 Extent2D extent2D; ///< Size of texture
937 bool directWriteAccessEnabled; ///< Direct write access (mappable textures)
941 * @brief Texture tiling that directly refers to the tiling
942 * mode supported by the Vulkan. Other implementations
943 * of the backend may ignore the value.
945 enum class TextureTiling
952 * @brief Texture color attachment used by FramebufferCreateInfo
954 struct ColorAttachment
956 uint32_t attachmentId;
963 * @brief Depth stencil attachment used by FramebufferCreateInfo
965 struct DepthStencilAttachment
971 * @brief Submit flags
973 using SubmitFlags = uint32_t;
978 enum class SubmitFlagBits : uint32_t
980 FLUSH = 1 << 0, // Flush immediately
981 DONT_OPTIMIZE = 1 << 1 // Tells controller not to optimize commands
985 inline SubmitFlags operator|(T flags, SubmitFlagBits bit)
987 return static_cast<SubmitFlags>(flags) | static_cast<SubmitFlags>(bit);
991 * @brief Describes command buffers submission
995 std::vector<CommandBuffer*> cmdBuffer;
1000 * @brief Shader language enum
1002 enum class ShaderLanguage
1012 * @brief Pipeline stages
1014 enum class PipelineStage
1021 TESSELATION_CONTROL,
1022 TESSELATION_EVALUATION,
1027 * @brief Vertex attribute format
1029 * TODO: to be replaced with Format
1031 enum class VertexInputAttributeFormat
1042 * @brief Type of texture
1044 enum class TextureType
1052 * @brief Describes pipeline's shading stages
1054 * Shader state binds shader and pipeline stage that the
1055 * shader will be executed. The shader may be created with
1056 * pipeline stage and the pipelineStage member may be ignored
1057 * by setting inheritPipelineStage to true.
1061 const Shader* shader{nullptr}; // shader to attach
1062 PipelineStage pipelineStage{}; // pipeline stage to execute the shader
1063 bool inheritPipelineStage{false}; // stage inheritance
1065 auto& SetShader(const Shader& value)
1071 auto& SetPipelineStage(PipelineStage value)
1073 pipelineStage = value;
1077 auto& SetInheritPipelineStage(bool value)
1079 inheritPipelineStage = value;
1085 * @brief Flag determining usage of texture
1087 using TextureUsageFlags = uint32_t;
1088 enum class TextureUsageFlagBits : uint32_t
1091 COLOR_ATTACHMENT = 1 << 1,
1092 DEPTH_STENCIL_ATTACHMENT = 1 << 2,
1096 template<typename T>
1097 inline TextureUsageFlags operator|(T flags, TextureUsageFlagBits bit)
1099 return static_cast<TextureUsageFlags>(flags) | static_cast<TextureUsageFlags>(bit);
1102 using TextureFormat = Dali::Graphics::Format;
1105 * @brief Texture mipmap disable/enable enum
1107 enum class TextureMipMapFlag
1114 * @brief Depth/stencil attachment flag
1116 enum class TextureDepthStencilFlag
1125 * @brief Layout of texture
1127 * Specifies how the memory will be allocated, organized and accessed.
1129 enum class TextureLayout
1131 LINEAR, ///< Creates linear memory, mapping possible
1132 OPTIMAL ///< Usually, read-only memory, driver-optimal layout
1136 * @brief Level of command buffer
1138 enum class CommandBufferLevel
1140 PRIMARY, ///< Primary buffer can be executed on its own
1141 SECONDARY ///< Secondary buffer must be executed within scope of Primary buffer
1145 * @brief Enum indicating whether shader source
1146 * is text-based or binary.
1148 enum class ShaderSourceMode
1155 * @brief Memory usage flags to be set when mapping the buffer
1157 using MemoryUsageFlags = uint32_t;
1158 enum class MemoryUsageFlagBits : uint32_t
1162 PERSISTENT = 1 << 2,
1163 ASYNCHRONOUS = 1 << 3,
1167 template<typename T>
1168 inline MemoryUsageFlags operator|(T flags, MemoryUsageFlagBits bit)
1170 return static_cast<MemoryUsageFlags>(flags) | static_cast<MemoryUsageFlags>(bit);
1174 * @brief Describes buffer mapping details
1176 struct MapBufferInfo
1179 MemoryUsageFlags usage;
1185 * @brief Describes buffer mapping details
1186 * TODO: mapping by texture level and layer
1188 struct MapTextureInfo
1191 MemoryUsageFlags usage;
1197 * @brief GraphicsStructureType enum is used by all create info structures
1198 * in order to identify by the implementation which structure it is
1201 enum class GraphicsStructureType : uint32_t
1203 BUFFER_CREATE_INFO_STRUCT,
1204 COMMAND_BUFFER_CREATE_INFO_STRUCT,
1205 FRAMEBUFFER_CREATE_INFO_STRUCT,
1206 PIPELINE_CREATE_INFO_STRUCT,
1207 RENDERPASS_CREATE_INFO_STRUCT,
1208 SAMPLER_CREATE_INFO_STRUCT,
1209 SHADER_CREATE_INFO_STRUCT,
1210 TEXTURE_CREATE_INFO_STRUCT,
1211 RENDER_TARGET_CREATE_INFO_STRUCT
1215 * @brief Helper function to be used by the extension developers
1217 * The value of custom type must be unique and recognizable by the
1220 * @param customValue Custom value of GraphicsStructureType
1221 * @return Integer converted to GraphicsStructureType
1223 inline GraphicsStructureType GraphicsExtensionType(uint32_t customValue)
1225 return static_cast<GraphicsStructureType>(customValue);
1229 * @brief The allocation callbacks may be passed when the object is created.
1231 struct AllocationCallbacks
1233 void* userData = nullptr; ///< User data passed to the allocator
1234 void* (*allocCallback)(size_t size, size_t alignment, void* userData) = nullptr;
1235 void* (*reallocCallback)(void* original, size_t size, size_t alignment, void* userData) = nullptr;
1236 void (*freeCallback)(void* memory, void* userData) = nullptr;
1240 * @brief The ExtensionCreateInfo structure should be a base of any
1241 * extension create info structure. The structure isn't virtual
1242 * so the implementation must prevent slicing it.
1244 struct ExtensionCreateInfo
1246 GraphicsStructureType type{};
1247 ExtensionCreateInfo* nextExtension{};
1251 * @brief Default deleter for graphics unique pointers
1253 * Returned unique_ptr may require custom deleter. To get it working
1254 * with std::unique_ptr the custom type is used with polymorphic deleter
1257 struct DefaultDeleter
1259 DefaultDeleter() = default;
1262 * @brief Conversion constructor
1264 * This constructor will set the lambda for type passed
1267 template<class P, template<typename> typename U>
1268 DefaultDeleter(const U<P>& deleter)
1270 deleteFunction = [](T* object) { U<P>()(static_cast<P*>(object)); };
1274 * @brief Conversion constructor from DefaultDelete<P>
1276 * This constructor transfers deleteFunction only
1279 explicit DefaultDeleter(const DefaultDeleter<P>& deleter)
1281 deleteFunction = decltype(deleteFunction)(deleter.deleteFunction);
1285 * @brief Default deleter
1287 * Default deleter will use standard 'delete' call in order
1288 * to discard graphics objects unless a custom deleter was
1291 * @param[in] object Object to delete
1293 void operator()(T* object)
1297 deleteFunction(object);
1305 void (*deleteFunction)(T* object){nullptr}; ///< Custom delete function
1309 * unique_ptr defined in the Graphics scope
1311 template<class T, class D = DefaultDeleter<T>>
1312 using UniquePtr = std::unique_ptr<T, D>;
1315 * @brief MakeUnique<> version that returns Graphics::UniquePtr
1316 * @param[in] args Arguments for construction
1319 template<class T, class Deleter = DefaultDeleter<T>, class... Args>
1320 std::enable_if_t<!std::is_array<T>::value, Graphics::UniquePtr<T>>
1321 MakeUnique(Args&&... args)
1323 return UniquePtr<T>(new T(std::forward<Args>(args)...), Deleter());
1326 } // namespace Graphics
1329 #endif //DALI_GRAPHICS_API_TYPES_H