ic
/
magnum
mirror of https://github.com/mosra/magnum.git
6
0
Fork 0
Code Issues Projects Releases Wiki Activity
Browse Source

Vk: rethink "creation" docs. 

Although the APIs don't look like that right now, in many cases creation
of a particular Vulkan object isn't all that's there for it. So change
the section names from a generic "Usage" to "Creation".
pull/491/head
Vladimír Vondruš 5 years ago
parent
299a17f95b
commit
98a69fc568
12 changed files with 92 additions and 90 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 72
      doc/snippets/MagnumVk.cpp
  2. 12
      src/Magnum/Vk/Buffer.h
  3. 10
      src/Magnum/Vk/CommandPool.h
  4. 12
      src/Magnum/Vk/Device.h
  5. 4
      src/Magnum/Vk/DeviceProperties.h
  6. 6
      src/Magnum/Vk/ExtensionProperties.h
  7. 12
      src/Magnum/Vk/Image.h
  8. 13
      src/Magnum/Vk/Instance.h
  9. 5
      src/Magnum/Vk/LayerProperties.h
  10. 8
      src/Magnum/Vk/Memory.h
  11. 20
      src/Magnum/Vk/RenderPass.h
  12. 8
      src/Magnum/Vk/Shader.h

72
doc/snippets/MagnumVk.cpp
Unescape View File

@ -121,17 +121,17 @@ Vk::Device device{instance, std::move(info)};
{ {
Vk::Device device{NoCreate}; Vk::Device device{NoCreate};
/* [Buffer-usage] */ /* [Buffer-creation] */
Vk::Buffer buffer{device, Vk::Buffer buffer{device,
Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, 1024*1024}, Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, 1024*1024},
Vk::MemoryFlag::DeviceLocal Vk::MemoryFlag::DeviceLocal
}; };
/* [Buffer-usage] */ /* [Buffer-creation] */
} }
{ {
Vk::Device device{NoCreate}; Vk::Device device{NoCreate};
/* [Buffer-usage-custom-allocation] */ /* [Buffer-creation-custom-allocation] */
Vk::Buffer buffer{device, Vk::Buffer buffer{device,
Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, 1024*1024}, Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, 1024*1024},
NoAllocate NoAllocate
@ -145,40 +145,40 @@ Vk::Memory memory{device, Vk::MemoryAllocateInfo{
}}; }};
buffer.bindMemory(memory, 0); buffer.bindMemory(memory, 0);
/* [Buffer-usage-custom-allocation] */ /* [Buffer-creation-custom-allocation] */
} }
{ {
/* [CommandPool-usage] */ /* [CommandPool-creation] */
Vk::Device device{DOXYGEN_IGNORE(NoCreate)}; Vk::Device device{DOXYGEN_IGNORE(NoCreate)};
Vk::CommandPool graphicsCommandPool{device, Vk::CommandPoolCreateInfo{ Vk::CommandPool graphicsCommandPool{device, Vk::CommandPoolCreateInfo{
device.properties().pickQueueFamily(Vk::QueueFlag::Graphics) device.properties().pickQueueFamily(Vk::QueueFlag::Graphics)
}}; }};
/* [CommandPool-usage] */ /* [CommandPool-creation] */
/* [CommandPool-usage-allocate] */ /* [CommandPool-allocation] */
Vk::CommandBuffer commandBuffer = graphicsCommandPool.allocate(); Vk::CommandBuffer commandBuffer = graphicsCommandPool.allocate();
// fill the buffer, submit … // fill the buffer, submit …
/* [CommandPool-usage-allocate] */ /* [CommandPool-allocation] */
} }
{ {
Vk::Instance instance; Vk::Instance instance;
/* [Device-usage-construct-queue] */ /* [Device-creation-construct-queue] */
Vk::Queue queue{NoCreate}; Vk::Queue queue{NoCreate};
Vk::Device device{instance, Vk::DeviceCreateInfo{Vk::pickDevice(instance)} Vk::Device device{instance, Vk::DeviceCreateInfo{Vk::pickDevice(instance)}
.addQueues(Vk::QueueFlag::Graphics, {0.0f}, {queue}) .addQueues(Vk::QueueFlag::Graphics, {0.0f}, {queue})
}; };
/* [Device-usage-construct-queue] */ /* [Device-creation-construct-queue] */
} }
{ {
Vk::Instance instance; Vk::Instance instance;
Vk::DeviceProperties properties{NoCreate}; Vk::DeviceProperties properties{NoCreate};
using namespace Containers::Literals; using namespace Containers::Literals;
/* [Device-usage-extensions] */ /* [Device-creation-extensions] */
Vk::Device device{instance, Vk::DeviceCreateInfo{DOXYGEN_IGNORE(properties)} Vk::Device device{instance, Vk::DeviceCreateInfo{DOXYGEN_IGNORE(properties)}
DOXYGEN_IGNORE() DOXYGEN_IGNORE()
.addEnabledExtensions< // predefined extensions .addEnabledExtensions< // predefined extensions
@ -186,13 +186,13 @@ Vk::Device device{instance, Vk::DeviceCreateInfo{DOXYGEN_IGNORE(properties)}
Vk::Extensions::KHR::device_group>() Vk::Extensions::KHR::device_group>()
.addEnabledExtensions({"VK_NV_mesh_shader"_s}) // can be plain strings too .addEnabledExtensions({"VK_NV_mesh_shader"_s}) // can be plain strings too
}; };
/* [Device-usage-extensions] */ /* [Device-creation-extensions] */
} }
{ {
Vk::Instance instance; Vk::Instance instance;
using namespace Containers::Literals; using namespace Containers::Literals;
/* [Device-usage-check-supported] */ /* [Device-creation-check-supported] */
Vk::DeviceProperties properties = Vk::pickDevice(instance); Vk::DeviceProperties properties = Vk::pickDevice(instance);
Vk::ExtensionProperties extensions = properties.enumerateExtensionProperties(); Vk::ExtensionProperties extensions = properties.enumerateExtensionProperties();
@ -202,7 +202,7 @@ if(extensions.isSupported<Vk::Extensions::EXT::index_type_uint8>())
if(extensions.isSupported("VK_NV_mesh_shader"_s)) if(extensions.isSupported("VK_NV_mesh_shader"_s))
info.addEnabledExtensions({"VK_NV_mesh_shader"_s}); info.addEnabledExtensions({"VK_NV_mesh_shader"_s});
DOXYGEN_IGNORE() DOXYGEN_IGNORE()
/* [Device-usage-check-supported] */ /* [Device-creation-check-supported] */
} }
{ {
@ -246,17 +246,17 @@ if(device.isExtensionEnabled<Vk::Extensions::EXT::index_type_uint8>()) {
{ {
Vk::Device device{NoCreate}; Vk::Device device{NoCreate};
/* [Image-usage] */ /* [Image-creation] */
Vk::Image image{device, Vk::ImageCreateInfo2D{ Vk::Image image{device, Vk::ImageCreateInfo2D{
Vk::ImageUsage::Sampled, VK_FORMAT_R8G8B8A8_SRGB, {1024, 1024}, 1 Vk::ImageUsage::Sampled, VK_FORMAT_R8G8B8A8_SRGB, {1024, 1024}, 1
}, Vk::MemoryFlag::DeviceLocal }, Vk::MemoryFlag::DeviceLocal
}; };
/* [Image-usage] */ /* [Image-creation] */
} }
{ {
Vk::Device device{NoCreate}; Vk::Device device{NoCreate};
/* [Image-usage-custom-allocation] */ /* [Image-creation-custom-allocation] */
Vk::Image image{device, Vk::ImageCreateInfo2D{ Vk::Image image{device, Vk::ImageCreateInfo2D{
Vk::ImageUsage::Sampled, VK_FORMAT_R8G8B8A8_SRGB, {1024, 1024}, 1 Vk::ImageUsage::Sampled, VK_FORMAT_R8G8B8A8_SRGB, {1024, 1024}, 1
}, NoAllocate }, NoAllocate
@ -270,34 +270,34 @@ Vk::Memory memory{device, Vk::MemoryAllocateInfo{
}}; }};
image.bindMemory(memory, 0); image.bindMemory(memory, 0);
/* [Image-usage-custom-allocation] */ /* [Image-creation-custom-allocation] */
} }
{ {
int argc{}; int argc{};
const char** argv{}; const char** argv{};
/* [Instance-usage-minimal] */ /* [Instance-creation-minimal] */
Vk::Instance instance{{argc, argv}}; Vk::Instance instance{{argc, argv}};
/* [Instance-usage-minimal] */ /* [Instance-creation-minimal] */
} }
{ {
int argc{}; int argc{};
const char** argv{}; const char** argv{};
/* [Instance-usage] */ /* [Instance-creation] */
using namespace Containers::Literals; using namespace Containers::Literals;
Vk::Instance instance{Vk::InstanceCreateInfo{argc, argv} Vk::Instance instance{Vk::InstanceCreateInfo{argc, argv}
.setApplicationInfo("My Vulkan Application"_s, Vk::version(1, 2, 3)) .setApplicationInfo("My Vulkan Application"_s, Vk::version(1, 2, 3))
}; };
/* [Instance-usage] */ /* [Instance-creation] */
} }
{ {
int argc{}; int argc{};
const char** argv{}; const char** argv{};
using namespace Containers::Literals; using namespace Containers::Literals;
/* [Instance-usage-layers-extensions] */ /* [Instance-creation-layers-extensions] */
Vk::Instance instance{Vk::InstanceCreateInfo{argc, argv} Vk::Instance instance{Vk::InstanceCreateInfo{argc, argv}
DOXYGEN_IGNORE() DOXYGEN_IGNORE()
.addEnabledLayers({"VK_LAYER_KHRONOS_validation"_s}) .addEnabledLayers({"VK_LAYER_KHRONOS_validation"_s})
@ -306,14 +306,14 @@ Vk::Instance instance{Vk::InstanceCreateInfo{argc, argv}
Vk::Extensions::KHR::external_fence_capabilities>() Vk::Extensions::KHR::external_fence_capabilities>()
.addEnabledExtensions({"VK_KHR_xcb_surface"_s}) // can be plain strings too .addEnabledExtensions({"VK_KHR_xcb_surface"_s}) // can be plain strings too
}; };
/* [Instance-usage-layers-extensions] */ /* [Instance-creation-layers-extensions] */
} }
{ {
int argc{}; int argc{};
const char** argv{}; const char** argv{};
using namespace Containers::Literals; using namespace Containers::Literals;
/* [Instance-usage-check-supported] */ /* [Instance-creation-check-supported] */
/* Query layer and extension support */ /* Query layer and extension support */
Vk::LayerProperties layers = Vk::enumerateLayerProperties(); Vk::LayerProperties layers = Vk::enumerateLayerProperties();
Vk::InstanceExtensionProperties extensions = Vk::InstanceExtensionProperties extensions =
@ -329,7 +329,7 @@ if(extensions.isSupported<Vk::Extensions::EXT::debug_report>())
DOXYGEN_IGNORE() DOXYGEN_IGNORE()
Vk::Instance instance{info}; Vk::Instance instance{info};
/* [Instance-usage-check-supported] */ /* [Instance-creation-check-supported] */
} }
{ {
@ -375,7 +375,7 @@ if(instance.isExtensionEnabled<Vk::Extensions::EXT::debug_utils>()) {
{ {
Vk::Device device{NoCreate}; Vk::Device device{NoCreate};
Containers::ArrayView<const char> vertexData, indexData; Containers::ArrayView<const char> vertexData, indexData;
/* [Memory-usage] */ /* [Memory-allocation] */
/* Create buffers without allocating them */ /* Create buffers without allocating them */
Vk::Buffer vertices{device, Vk::Buffer vertices{device,
Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, vertexData.size()}, Vk::BufferCreateInfo{Vk::BufferUsage::VertexBuffer, vertexData.size()},
@ -404,7 +404,7 @@ const UnsignedLong indicesOffset = verticesRequirements.alignedSize(alignment);
/* Bind the respective sub-ranges to the buffers */ /* Bind the respective sub-ranges to the buffers */
vertices.bindMemory(memory, 0); vertices.bindMemory(memory, 0);
indices.bindMemory(memory, indicesOffset); indices.bindMemory(memory, indicesOffset);
/* [Memory-usage] */ /* [Memory-allocation] */
/* [Memory-mapping] */ /* [Memory-mapping] */
/* The memory gets unmapped again at the end of scope */ /* The memory gets unmapped again at the end of scope */
@ -419,7 +419,7 @@ indices.bindMemory(memory, indicesOffset);
{ {
Vk::Device device{DOXYGEN_IGNORE(NoCreate)}; Vk::Device device{DOXYGEN_IGNORE(NoCreate)};
/* [RenderPass-usage] */ /* [RenderPass-creation] */
Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{} Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
.setAttachments({ .setAttachments({
VK_FORMAT_R8G8B8A8_SRGB, VK_FORMAT_R8G8B8A8_SRGB,
@ -430,12 +430,12 @@ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
.setDepthStencilAttachment(1) .setDepthStencilAttachment(1)
) )
}; };
/* [RenderPass-usage] */ /* [RenderPass-creation] */
} }
{ {
Vk::Device device{DOXYGEN_IGNORE(NoCreate)}; Vk::Device device{DOXYGEN_IGNORE(NoCreate)};
/* [RenderPass-usage-load-store] */ /* [RenderPass-creation-load-store] */
Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{} Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
.setAttachments({ .setAttachments({
{VK_FORMAT_R8G8B8A8_SRGB, Vk::AttachmentLoadOperation::Clear, {}}, {VK_FORMAT_R8G8B8A8_SRGB, Vk::AttachmentLoadOperation::Clear, {}},
@ -443,12 +443,12 @@ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
}) })
DOXYGEN_IGNORE() DOXYGEN_IGNORE()
}; };
/* [RenderPass-usage-load-store] */ /* [RenderPass-creation-load-store] */
} }
{ {
Vk::Device device{DOXYGEN_IGNORE(NoCreate)}; Vk::Device device{DOXYGEN_IGNORE(NoCreate)};
/* [RenderPass-usage-layout] */ /* [RenderPass-creation-layout] */
Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{} Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
.setAttachments({ .setAttachments({
{VK_FORMAT_R8G8B8A8_SRGB, {VK_FORMAT_R8G8B8A8_SRGB,
@ -465,12 +465,12 @@ Vk::RenderPass renderPass{device, Vk::RenderPassCreateInfo{}
.setDepthStencilAttachment({1, Vk::ImageLayout::ColorAttachment}) .setDepthStencilAttachment({1, Vk::ImageLayout::ColorAttachment})
) )
}; };
/* [RenderPass-usage-layout] */ /* [RenderPass-creation-layout] */
} }
{ {
Vk::Device device{DOXYGEN_IGNORE(NoCreate)}; Vk::Device device{DOXYGEN_IGNORE(NoCreate)};
/* [Shader-usage] */ /* [Shader-creation] */
Vk::ShaderCreateInfo info{ Vk::ShaderCreateInfo info{
CORRADE_INTERNAL_ASSERT_EXPRESSION(Utility::Directory::read("shader.spv")) CORRADE_INTERNAL_ASSERT_EXPRESSION(Utility::Directory::read("shader.spv"))
}; };
@ -478,7 +478,7 @@ Vk::ShaderCreateInfo info{
DOXYGEN_IGNORE() DOXYGEN_IGNORE()
Vk::Shader shader{device, info}; Vk::Shader shader{device, info};
/* [Shader-usage] */ /* [Shader-creation] */
} }
{ {

12
src/Magnum/Vk/Buffer.h
Unescape View File

@ -97,8 +97,8 @@ CORRADE_ENUMSET_OPERATORS(BufferUsages)
@brief Buffer creation info @brief Buffer creation info
@m_since_latest @m_since_latest
Wraps a @type_vk_keyword{BufferCreateInfo}. See @ref Buffer for usage Wraps a @type_vk_keyword{BufferCreateInfo}. See
information. @ref Vk-Buffer-creation "Buffer creation" for usage information.
*/ */
class MAGNUM_VK_EXPORT BufferCreateInfo { class MAGNUM_VK_EXPORT BufferCreateInfo {
public: public:
@ -178,25 +178,25 @@ CORRADE_ENUMSET_OPERATORS(BufferCreateInfo::Flags)
Wraps a @type_vk_keyword{Buffer} and its memory. Wraps a @type_vk_keyword{Buffer} and its memory.
@section Vk-Buffer-usage Basic usage @section Vk-Buffer-creation Buffer creation
Pass a @ref BufferCreateInfo with desired usage and size to the @ref Buffer Pass a @ref BufferCreateInfo with desired usage and size to the @ref Buffer
constructor together with specifying @ref MemoryFlags for the allocation. constructor together with specifying @ref MemoryFlags for the allocation.
@snippet MagnumVk.cpp Buffer-usage @snippet MagnumVk.cpp Buffer-creation
@attention At this point, a dedicated allocation is used, subsequently @attention At this point, a dedicated allocation is used, subsequently
accessible through @ref dedicatedMemory(). This behavior may change in the accessible through @ref dedicatedMemory(). This behavior may change in the
future. future.
@section Vk-Buffer-usage-custom-allocation Custom memory allocation @subsection Vk-Buffer-creation-custom-allocation Custom memory allocation
Using @ref Buffer(Device&, const BufferCreateInfo&, NoAllocateT), the buffer Using @ref Buffer(Device&, const BufferCreateInfo&, NoAllocateT), the buffer
will be created without any memory bound. Buffer memory requirements can be will be created without any memory bound. Buffer memory requirements can be
then queried using @ref memoryRequirements() and an allocated memory bound with then queried using @ref memoryRequirements() and an allocated memory bound with
@ref bindMemory(). See @ref Memory for further details about memory allocation. @ref bindMemory(). See @ref Memory for further details about memory allocation.
@snippet MagnumVk.cpp Buffer-usage-custom-allocation @snippet MagnumVk.cpp Buffer-creation-custom-allocation
Using @ref bindDedicatedMemory() instead of @ref bindMemory() will transfer Using @ref bindDedicatedMemory() instead of @ref bindMemory() will transfer
ownership of the @ref Memory to the buffer instance, making it subsequently ownership of the @ref Memory to the buffer instance, making it subsequently

10
src/Magnum/Vk/CommandPool.h
Unescape View File

@ -44,8 +44,8 @@ namespace Magnum { namespace Vk {
@brief Command pool creation info @brief Command pool creation info
@m_since_latest @m_since_latest
Wraps a @type_vk_keyword{CommandPoolCreateInfo}. See @ref CommandPool for usage Wraps a @type_vk_keyword{CommandPoolCreateInfo}. See
information. @ref Vk-CommandPool-creation "Command pool creation" for usage information.
*/ */
class MAGNUM_VK_EXPORT CommandPoolCreateInfo { class MAGNUM_VK_EXPORT CommandPoolCreateInfo {
public: public:
@ -180,20 +180,20 @@ CORRADE_ENUMSET_OPERATORS(CommandPoolResetFlags)
Wraps a @type_vk_keyword{CommandPool} and handles allocation of Wraps a @type_vk_keyword{CommandPool} and handles allocation of
@ref CommandBuffer "CommandBuffer"s. @ref CommandBuffer "CommandBuffer"s.
@section Vk-CommandPool-usage Usage @section Vk-CommandPool-creation Command pool creation and buffer allocation
A @ref CommandPoolCreateInfo doesn't need many inputs --- the only required is A @ref CommandPoolCreateInfo doesn't need many inputs --- the only required is
queue family index coming from @ref DeviceProperties of the device it's created queue family index coming from @ref DeviceProperties of the device it's created
on: on:
@snippet MagnumVk.cpp CommandPool-usage @snippet MagnumVk.cpp CommandPool-creation
After that, you can allocate command buffers as follows. The command buffers After that, you can allocate command buffers as follows. The command buffers
are freed at the end of their instance lifetime, you can also put all allocated are freed at the end of their instance lifetime, you can also put all allocated
buffers back to initial state by calling @ref reset(), or alternatively reset buffers back to initial state by calling @ref reset(), or alternatively reset
each buffer separately using @ref CommandBuffer::reset(). each buffer separately using @ref CommandBuffer::reset().
@snippet MagnumVk.cpp CommandPool-usage-allocate @snippet MagnumVk.cpp CommandPool-allocation
*/ */
class MAGNUM_VK_EXPORT CommandPool { class MAGNUM_VK_EXPORT CommandPool {
public: public:

12
src/Magnum/Vk/Device.h
Unescape View File

@ -53,8 +53,8 @@ namespace Implementation {
@brief Device creation info @brief Device creation info
@m_since_latest @m_since_latest
Wraps a @type_vk_keyword{DeviceCreateInfo}. See @ref Device for usage Wraps a @type_vk_keyword{DeviceCreateInfo}. See
information. @ref Vk-Device-creation "Device creation" for usage information.
*/ */
class MAGNUM_VK_EXPORT DeviceCreateInfo { class MAGNUM_VK_EXPORT DeviceCreateInfo {
public: public:
@ -294,7 +294,7 @@ CORRADE_ENUMSET_OPERATORS(DeviceCreateInfo::Flags)
Wraps a @type_vk_keyword{Device} and stores device-specific Vulkan function Wraps a @type_vk_keyword{Device} and stores device-specific Vulkan function
pointers. pointers.
@section Vk-Device-usage Usage @section Vk-Device-creation Device creation
With an @ref Instance ready, a device has to be picked first. Commonly it's With an @ref Instance ready, a device has to be picked first. Commonly it's
done by calling @ref pickDevice() and letting the library choose. This done by calling @ref pickDevice() and letting the library choose. This
@ -311,7 +311,7 @@ That's done by creating an empty @ref Queue instance and then referencing it
from @ref DeviceCreateInfo::addQueues(). After the device is constructed, the from @ref DeviceCreateInfo::addQueues(). After the device is constructed, the
queue gets populated and is ready to be used. queue gets populated and is ready to be used.
@snippet MagnumVk.cpp Device-usage-construct-queue @snippet MagnumVk.cpp Device-creation-construct-queue
In the above snippet, we requested a graphics queue via a convenience API. The In the above snippet, we requested a graphics queue via a convenience API. The
information about available queues and other device properties is stored in a information about available queues and other device properties is stored in a
@ -326,12 +326,12 @@ both string names as well as predefined *device* extensions from the
@ref Extensions namespace. Later on, presence of predefined extensions can be @ref Extensions namespace. Later on, presence of predefined extensions can be
checked with @ref isExtensionEnabled(). checked with @ref isExtensionEnabled().
@snippet MagnumVk.cpp Device-usage-extensions @snippet MagnumVk.cpp Device-creation-extensions
Usually you'll be first checking for extension availability instead, which is Usually you'll be first checking for extension availability instead, which is
again accessible through the @ref DeviceProperties instance: again accessible through the @ref DeviceProperties instance:
@snippet MagnumVk.cpp Device-usage-check-supported @snippet MagnumVk.cpp Device-creation-check-supported
With both @ref Instance and @ref Device created, you can proceed to setting up With both @ref Instance and @ref Device created, you can proceed to setting up
a @ref CommandPool. a @ref CommandPool.

4
src/Magnum/Vk/DeviceProperties.h
Unescape View File

@ -253,8 +253,8 @@ of @type_vk_keyword{PhysicalDeviceProperties},
@type_vk_keyword{PhysicalDeviceQueueFamilyProperties} and @type_vk_keyword{PhysicalDeviceQueueFamilyProperties} and
@type_vk_keyword{PhysicalDeviceMemoryProperties}. @type_vk_keyword{PhysicalDeviceMemoryProperties}.
See the @ref Vk-Device-usage "Device class docs" for an example of using this See the @ref Vk-Device-creation "Device creation docs" for an example of using
class for enumerating available devices and picking one of them. this class for enumerating available devices and picking one of them.
@see @ref pickDevice(), @ref enumerateDevices() @see @ref pickDevice(), @ref enumerateDevices()
*/ */

6
src/Magnum/Vk/ExtensionProperties.h
Unescape View File

@ -48,9 +48,9 @@ namespace Magnum { namespace Vk {
Provides a searchable container of Vulkan device extensions enumerated with Provides a searchable container of Vulkan device extensions enumerated with
@ref DeviceProperties::enumerateExtensionProperties(). @ref DeviceProperties::enumerateExtensionProperties().
See the @ref Vk-Device-usage "Device class docs" for an example of using this See the @ref Vk-Device-creation "Device creation docs" for an example of using
class for checking available extensions before enabling them on a device. See this class for checking available extensions before enabling them on a device.
@ref Vk-Instance-usage "Instance class docs" for the same but using See @ref Vk-Instance-creation "Instance creation docs" for the same but using
@ref InstanceExtensionProperties. @ref InstanceExtensionProperties.
@see @type_vk_keyword{ExtensionProperties} @see @type_vk_keyword{ExtensionProperties}

12
src/Magnum/Vk/Image.h
Unescape View File

@ -225,8 +225,8 @@ enum class ImageLayout: Int {
@brief Image creation info @brief Image creation info
@m_since_latest @m_since_latest
Wraps a @type_vk_keyword{ImageCreateInfo}. See @ref Image for usage Wraps a @type_vk_keyword{ImageCreateInfo}. See
information. @ref Vk-Image-creation "Image creation" for usage information.
@see @ref ImageCreateInfo1D, @ref ImageCreateInfo2D, @ref ImageCreateInfo3D, @see @ref ImageCreateInfo1D, @ref ImageCreateInfo2D, @ref ImageCreateInfo3D,
@ref ImageCreateInfo1DArray, @ref ImageCreateInfo2DArray, @ref ImageCreateInfo1DArray, @ref ImageCreateInfo2DArray,
@ref ImageCreateInfoCubeMap, @ref ImageCreateInfoCubeMapArray @ref ImageCreateInfoCubeMap, @ref ImageCreateInfoCubeMapArray
@ -525,26 +525,26 @@ class ImageCreateInfoCubeMapArray: public ImageCreateInfo {
Wraps a @type_vk_keyword{Image} and its memory. Wraps a @type_vk_keyword{Image} and its memory.
@section Vk-Image-usage Basic usage @section Vk-Image-creation Image creation
Pass one of the @ref ImageCreateInfo subclasses depending on desired image type Pass one of the @ref ImageCreateInfo subclasses depending on desired image type
with desired usage, format, size and other propoerties to the @ref Image with desired usage, format, size and other propoerties to the @ref Image
constructor together with specifying @ref MemoryFlags for memory allocation. constructor together with specifying @ref MemoryFlags for memory allocation.
@snippet MagnumVk.cpp Image-usage @snippet MagnumVk.cpp Image-creation
@attention At this point, a dedicated allocation is used, subsequently @attention At this point, a dedicated allocation is used, subsequently
accessible through @ref dedicatedMemory(). This behavior may change in the accessible through @ref dedicatedMemory(). This behavior may change in the
future. future.
@section Vk-Image-usage-custom-allocation Custom memory allocation @subsection Vk-Image-creation-custom-allocation Custom memory allocation
Using @ref Image(Device&, const ImageCreateInfo&, NoAllocateT), the image will Using @ref Image(Device&, const ImageCreateInfo&, NoAllocateT), the image will
be created without any memory attached. Image memory requirements can be be created without any memory attached. Image memory requirements can be
subsequently queried using @ref memoryRequirements() and an allocated memory subsequently queried using @ref memoryRequirements() and an allocated memory
bound with @ref bindMemory(). See @ref Memory for further details about memory allocation. bound with @ref bindMemory(). See @ref Memory for further details about memory allocation.
@snippet MagnumVk.cpp Image-usage-custom-allocation @snippet MagnumVk.cpp Image-creation-custom-allocation
Using @ref bindDedicatedMemory() instead of @ref bindMemory() will transfer Using @ref bindDedicatedMemory() instead of @ref bindMemory() will transfer
ownership of the @ref Memory to the image instance, making it subsequently ownership of the @ref Memory to the image instance, making it subsequently

13
src/Magnum/Vk/Instance.h
Unescape View File

@ -52,7 +52,8 @@ namespace Implementation {
@m_since_latest @m_since_latest
Wraps a @type_vk_keyword{InstanceCreateInfo} and Wraps a @type_vk_keyword{InstanceCreateInfo} and
@type_vk_keyword{ApplicationInfo}. See @ref Instance for usage information. @type_vk_keyword{ApplicationInfo}. See
@ref Vk-Instance-creation "Instance creation" for usage information.
*/ */
class MAGNUM_VK_EXPORT InstanceCreateInfo { class MAGNUM_VK_EXPORT InstanceCreateInfo {
public: public:
@ -244,19 +245,19 @@ CORRADE_ENUMSET_OPERATORS(InstanceCreateInfo::Flags)
Wraps a @type_vk_keyword{Instance} and stores instance-specific Vulkan function Wraps a @type_vk_keyword{Instance} and stores instance-specific Vulkan function
pointers. pointers.
@section Vk-Instance-usage Usage @section Vk-Instance-creation Instance creation
While an @ref Instance can be default-constructed without much fuss, it's While an @ref Instance can be default-constructed without much fuss, it's
recommended to pass a @ref InstanceCreateInfo with at least the `argc` / `argv` recommended to pass a @ref InstanceCreateInfo with at least the `argc` / `argv`
pair, which allows you to use various `--magnum-*` pair, which allows you to use various `--magnum-*`
@ref Vk-Instance-command-line "command-line options": @ref Vk-Instance-command-line "command-line options":
@snippet MagnumVk.cpp Instance-usage-minimal @snippet MagnumVk.cpp Instance-creation-minimal
In addition to command-line arguments, setting application info isn't strictly In addition to command-line arguments, setting application info isn't strictly
required either, but may be beneficial for the driver: required either, but may be beneficial for the driver:
@snippet MagnumVk.cpp Instance-usage @snippet MagnumVk.cpp Instance-creation
<b></b> <b></b>
@ -277,14 +278,14 @@ both string names as well as predefined *instance* extensions from the
@ref Extensions namespace. Later on, presence of predefined extensions can be @ref Extensions namespace. Later on, presence of predefined extensions can be
checked with @ref isExtensionEnabled(). checked with @ref isExtensionEnabled().
@snippet MagnumVk.cpp Instance-usage-layers-extensions @snippet MagnumVk.cpp Instance-creation-layers-extensions
However, with the above approach, if any layer or extension isn't available, However, with the above approach, if any layer or extension isn't available,
the instance creation will abort. The recommended workflow is thus first the instance creation will abort. The recommended workflow is thus first
checking layer and extension availability using @ref enumerateLayerProperties() checking layer and extension availability using @ref enumerateLayerProperties()
and @ref enumerateInstanceExtensionProperties(): and @ref enumerateInstanceExtensionProperties():
@snippet MagnumVk.cpp Instance-usage-check-supported @snippet MagnumVk.cpp Instance-creation-check-supported
Next step after creating a Vulkan instance is picking and creating a Next step after creating a Vulkan instance is picking and creating a
@ref Device. @ref Device.

5
src/Magnum/Vk/LayerProperties.h
Unescape View File

@ -51,8 +51,9 @@ and the assumption is that no drivers currently use rely on these anymore. See
[§ 37.3.1](https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/chap38.html#extendingvulkan-layers-devicelayerdeprecation) [§ 37.3.1](https://www.khronos.org/registry/vulkan/specs/1.2-extensions/html/chap38.html#extendingvulkan-layers-devicelayerdeprecation)
for more information. for more information.
See the @ref Vk-Instance-usage "Instance class docs" for an example of using See the @ref Vk-Instance-creation "Instance creation docs" for an example of
this class for checking available layers before enabling them on an instance. using this class for checking available layers before enabling them on an
instance.
@see @ref ExtensionProperties, @ref enumerateInstanceExtensionProperties(), @see @ref ExtensionProperties, @ref enumerateInstanceExtensionProperties(),
@type_vk_keyword{LayerProperties} @type_vk_keyword{LayerProperties}

8
src/Magnum/Vk/Memory.h
Unescape View File

@ -201,8 +201,8 @@ class MAGNUM_VK_EXPORT MemoryRequirements {
@brief Memory allocation info @brief Memory allocation info
@m_since_latest @m_since_latest
Wraps a @type_vk_keyword{MemoryAllocateInfo}. See @ref Memory for usage Wraps a @type_vk_keyword{MemoryAllocateInfo}. See
information. @ref Vk-Memory-allocation "Memory allocation" for usage information.
*/ */
class MAGNUM_VK_EXPORT MemoryAllocateInfo { class MAGNUM_VK_EXPORT MemoryAllocateInfo {
public: public:
@ -262,7 +262,7 @@ class MAGNUM_VK_EXPORT MemoryAllocateInfo {
Wraps a @type_vk_keyword{DeviceMemory} and handles its allocation and mapping. Wraps a @type_vk_keyword{DeviceMemory} and handles its allocation and mapping.
@section Vk-Memory-usage Usage @section Vk-Memory-allocation Memory allocation
By default, the memory will get allocated for you during the creation of By default, the memory will get allocated for you during the creation of
@ref Buffer, @ref Image and other objects. In case you want to handle the @ref Buffer, @ref Image and other objects. In case you want to handle the
@ -283,7 +283,7 @@ tag to constructors of these objects), it consists of these steps:
The following example allocates a single block memory for two buffers, one The following example allocates a single block memory for two buffers, one
containing vertex and the other index data: containing vertex and the other index data:
@snippet MagnumVk.cpp Memory-usage @snippet MagnumVk.cpp Memory-allocation
@section Vk-Memory-mapping Memory mapping @section Vk-Memory-mapping Memory mapping

20
src/Magnum/Vk/RenderPass.h
Unescape View File

@ -800,8 +800,8 @@ class MAGNUM_VK_EXPORT SubpassDependency {
@m_since_latest @m_since_latest
Wraps a @type_vk_keyword{RenderPassCreateInfo2} / Wraps a @type_vk_keyword{RenderPassCreateInfo2} /
@type_vk_keyword{RenderPassCreateInfo}. See @ref RenderPass for usage @type_vk_keyword{RenderPassCreateInfo}. See
information. @ref Vk-RenderPass-creation "Render pass creation" for usage information.
@section Vk-RenderPassCreateInfo-compatibility Compatibility with VkRenderPassCreateInfo @section Vk-RenderPassCreateInfo-compatibility Compatibility with VkRenderPassCreateInfo
@ -1011,12 +1011,12 @@ descriptions, subpasses and their dependencies. The render pass description is
independent of any specific image views used for attachments, these two are independent of any specific image views used for attachments, these two are
connected together in a framebuffer. connected together in a framebuffer.
@section Vk-RenderPass-usage Basic usage @section Vk-RenderPass-creation Render pass creation
A render pass is a set of attachments, described by @ref AttachmentDescription @ref RenderPassCreateInfo is a set of attachments, described by
instances, subpasses operating on those attachments, described by a @ref AttachmentDescription instances, subpasses operating on those attachments,
@ref SubpassDescription using @ref AttachmentReference instances, and subpass described by a @ref SubpassDescription using @ref AttachmentReference
dependencies, described by @ref SubpassDependency. instances, and subpass dependencies, described by @ref SubpassDependency.
A render pass has to have at least one subpass. It's common to have just one A render pass has to have at least one subpass. It's common to have just one
subpass but while the subpass isn't required to operate on any attachments, subpass but while the subpass isn't required to operate on any attachments,
@ -1028,7 +1028,7 @@ on a color and a combined depth/stencil attachment. The main parameter an
@ref RenderPassCreateInfo::setAttachments() array, and it's actually @ref RenderPassCreateInfo::setAttachments() array, and it's actually
@ref AttachmentReference instances: @ref AttachmentReference instances:
@snippet MagnumVk.cpp RenderPass-usage @snippet MagnumVk.cpp RenderPass-creation
The above again does a conservative estimate that you'd want to preserve the The above again does a conservative estimate that you'd want to preserve the
attachment contents between render passes. Usually you'd want to clear the attachment contents between render passes. Usually you'd want to clear the
@ -1039,7 +1039,7 @@ passing appropriate @ref AttachmentLoadOperation /
conveniently the zero values, which means you can use @cpp {} @ce instead of conveniently the zero values, which means you can use @cpp {} @ce instead of
typing them out in full: typing them out in full:
@snippet MagnumVk.cpp RenderPass-usage-load-store @snippet MagnumVk.cpp RenderPass-creation-load-store
Vulkan makes heavy use of image layouts for optimal memory access Vulkan makes heavy use of image layouts for optimal memory access
and in all the cases above, @ref ImageLayout::General is used as an implicit and in all the cases above, @ref ImageLayout::General is used as an implicit
@ -1051,7 +1051,7 @@ more optimal by explicitly specifying both a concrete initial and final layout
in the @ref AttachmentDescription constructors and in in the @ref AttachmentDescription constructors and in
each @link AttachmentReference @endlink: each @link AttachmentReference @endlink:
@snippet MagnumVk.cpp RenderPass-usage-layout @snippet MagnumVk.cpp RenderPass-creation-layout
*/ */
class MAGNUM_VK_EXPORT RenderPass { class MAGNUM_VK_EXPORT RenderPass {
public: public:

8
src/Magnum/Vk/Shader.h
Unescape View File

@ -44,8 +44,8 @@ namespace Magnum { namespace Vk {
@brief Shader creation info @brief Shader creation info
@m_since_latest @m_since_latest
Wraps a @type_vk_keyword{ShaderModuleCreateInfo}. See @ref Shader for usage Wraps a @type_vk_keyword{ShaderModuleCreateInfo}. See
information. @ref Vk-Shader-creation "Shader creation" for usage information.
*/ */
class MAGNUM_VK_EXPORT ShaderCreateInfo { class MAGNUM_VK_EXPORT ShaderCreateInfo {
public: public:
@ -173,7 +173,7 @@ CORRADE_ENUMSET_OPERATORS(ShaderCreateInfo::Flags)
Wraps a @type_vk_keyword{ShaderModule}. Wraps a @type_vk_keyword{ShaderModule}.
@section Vk-Shader-usage Usage @section Vk-Shader-creation Shader creation
The @ref ShaderCreateInfo structure takes a single required parameter, which is The @ref ShaderCreateInfo structure takes a single required parameter, which is
the SPIR-V binary. Besides accepting a @ref Corrade::Containers::ArrayView<const void>, the SPIR-V binary. Besides accepting a @ref Corrade::Containers::ArrayView<const void>,
@ -182,7 +182,7 @@ to which any container is convertible, it can also take ownership of a
keeping a loaded file in scope until it's consumed by the @ref Shader keeping a loaded file in scope until it's consumed by the @ref Shader
constructor: constructor:
@snippet MagnumVk.cpp Shader-usage @snippet MagnumVk.cpp Shader-creation
*/ */
class MAGNUM_VK_EXPORT Shader { class MAGNUM_VK_EXPORT Shader {
public: public:

Write Preview
Loading…
Cancel
Save