diff --git a/doc/developers.dox b/doc/developers.dox index 7e1985c64..bebabdf9e 100644 --- a/doc/developers.dox +++ b/doc/developers.dox @@ -792,6 +792,11 @@ unless it doesn't affect public API at all. - The main constructor(s) should explicitly list what structure fields are filled to which value, and if the constructor isn't enough to get a working state, it should also clearly mention what needs to be done next +- For everything non-essential or what isn't practical to be set in + constructor a setter should be added. If applicable, document what + subsequent calls to the same function result in (for example when a list + gets cleared while all other functions append to lists). The docs should + again list what underlying structure fields are set to which value. - Every class should have a @ref NoInitT constructor, which keeps the structure uninitialized and *doesn't* allocate any internal state - Every class should have a constructor taking the underlying Vulkan diff --git a/src/Magnum/Vk/DeviceCreateInfo.h b/src/Magnum/Vk/DeviceCreateInfo.h index 088a5ad14..6a73d3a73 100644 --- a/src/Magnum/Vk/DeviceCreateInfo.h +++ b/src/Magnum/Vk/DeviceCreateInfo.h @@ -175,10 +175,18 @@ class MAGNUM_VK_EXPORT DeviceCreateInfo { * All listed extensions are expected to be supported either globally * or in at least one of the enabled layers, use * @ref ExtensionProperties::isSupported() to check for their presence. - * * The function makes copies of string views that are not global or * null-terminated, use the @link Containers::Literals::operator""_s() @endlink * literal to prevent that where possible. + * + * The following @type_vk{DeviceCreateInfo} fields are set by this + * function: + * + * - `enabledExtensionCount` to the count of extensions added + * previously by this function plus @cpp extensions.size() @ce + * - `pEnabledExtensionNames` to an array containing all extension + * strings added previously by this function together with ones + * from @p extensions */ DeviceCreateInfo& addEnabledExtensions(Containers::ArrayView extensions) &; /** @overload */ @@ -215,8 +223,13 @@ class MAGNUM_VK_EXPORT DeviceCreateInfo { * corresponding extension enabled via @ref addEnabledExtensions(). Use * @ref DeviceProperties::features() to check for feature support. * - * Depending on what features are enabled, a subset of the following - * structures will be added to the `pNext` chain: + * If Vulkan 1.1 is not supported and + * @vk_extension{KHR,get_physical_device_properties2} is not enabled on + * the instance, the `pEnabledFeatures` field in + * @type_vk{DeviceCreateInfo} is set to the Vulkan 1.0 subset of + * @p features. Otherwise, depending on what features are enabled, a + * subset of the following structures will be added to the `pNext` + * chain: * * - @type_vk_keyword{PhysicalDeviceProtectedMemoryFeatures} (Vulkan * 1.1) @@ -292,6 +305,16 @@ class MAGNUM_VK_EXPORT DeviceCreateInfo { * @return Reference to self (for method chaining) * * At least one queue has to be added. + * + * The following @type_vk{DeviceCreateInfo} fields are set by this + * function: + * + * - `queueCreateInfoCount` to the count of queues added previously + * by this function plus @cpp queues.size() @ce + * - `pQueueCreateInfos` to an array containing all queue create + * infos added previously by this function together with ones + * from @p family and @p priorities + * * @see @ref DeviceProperties::pickQueueFamily() * @todoc link to addQueues(QueueFlags) once doxygen finally GROWS UP * and can link to &-qualified functions FFS @@ -331,8 +354,16 @@ class MAGNUM_VK_EXPORT DeviceCreateInfo { * @return Reference to self (for method chaining) * * Compared to @ref addQueues() this allows you to specify additional - * queue properties using the `pNext` chain. The info is uses as-is, + * queue properties using the `pNext` chain. The info is used as-is, * with all pointers expected to stay in scope until device creation. + * + * The following @type_vk{DeviceCreateInfo} fields are set by this + * function: + * + * - `queueCreateInfoCount` to the count of queues added previously + * by this function plus @cpp 1 @ce + * - `pQueueCreateInfos` to an array containing all queue create + * infos added previously by this function together with @p info */ DeviceCreateInfo& addQueues(const VkDeviceQueueCreateInfo& info) &; /** @overload */ diff --git a/src/Magnum/Vk/InstanceCreateInfo.h b/src/Magnum/Vk/InstanceCreateInfo.h index 24f91a1bf..08b6b17d0 100644 --- a/src/Magnum/Vk/InstanceCreateInfo.h +++ b/src/Magnum/Vk/InstanceCreateInfo.h @@ -159,6 +159,13 @@ class MAGNUM_VK_EXPORT InstanceCreateInfo { * The function makes copies of string views that are not global or * null-terminated, use the @link Containers::Literals::operator""_s() @endlink * literal to prevent that where possible. + * + * The following @type_vk{InstanceCreateInfo} fields are set by this + * function: + * + * - `pApplicationInfo` + * - @cpp pApplicationInfo->pApplicationName @ce to @p name + * - @cpp pApplicationInfo->applicationVersion @ce to @p version */ InstanceCreateInfo& setApplicationInfo(Containers::StringView name, Version version); @@ -175,6 +182,15 @@ class MAGNUM_VK_EXPORT InstanceCreateInfo { * The function makes copies of string views that are not global or * null-terminated, use the @link Containers::Literals::operator""_s() @endlink * literal to prevent that where possible. + * + * The following @type_vk{InstanceCreateInfo} fields are set by this + * function: + * + * - `enabledLayerCount` to the count of layers added previously by + * this function plus @cpp layers.size() @ce + * - `pEnabledLayerNames` to an array containing all layer strings + * added previously by this function together with ones from + * @p layers */ InstanceCreateInfo& addEnabledLayers(Containers::ArrayView layers); /** @overload */ @@ -195,6 +211,15 @@ class MAGNUM_VK_EXPORT InstanceCreateInfo { * The function makes copies of string views that are not global or * null-terminated, use the @link Containers::Literals::operator""_s() @endlink * literal to prevent that where possible. + * + * The following @type_vk{InstanceCreateInfo} fields are set by this + * function: + * + * - `enabledExtensionCount` to the count of extensions added + * previously by this function plus @cpp extensions.size() @ce + * - `pEnabledExtensionNames` to an array containing all extension + * strings added previously by this function together with ones + * from @p extensions */ InstanceCreateInfo& addEnabledExtensions(Containers::ArrayView extensions); /** @overload */ diff --git a/src/Magnum/Vk/RasterizationPipelineCreateInfo.h b/src/Magnum/Vk/RasterizationPipelineCreateInfo.h index 34ce4ddbf..0052641be 100644 --- a/src/Magnum/Vk/RasterizationPipelineCreateInfo.h +++ b/src/Magnum/Vk/RasterizationPipelineCreateInfo.h @@ -454,8 +454,8 @@ class MAGNUM_VK_EXPORT RasterizationPipelineCreateInfo { * @f$ [0.0, 1.0] @f$. * * The following @type_vk{GraphicsPipelineCreateInfo} and substructure - * fields are modified, in addition to `sType` of newly referenced - * structures: + * fields are modified by this function, in addition to `sType` of + * newly referenced structures: * * - `pViewportState` * - @cpp pViewportState->viewportCount @ce to @cpp 1 @ce @@ -501,8 +501,8 @@ class MAGNUM_VK_EXPORT RasterizationPipelineCreateInfo { * @brief Set dynamic states * * The following @type_vk{GraphicsPipelineCreateInfo} and substructure - * fields are modified, in addition to `sType` of newly referenced - * structures: + * fields are modified by this function, in addition to `sType` of + * newly referenced structures: * * - `pDynamicState` * - @cpp pDynamicState->dynamicStateCount @ce to count of values diff --git a/src/Magnum/Vk/RenderPassCreateInfo.h b/src/Magnum/Vk/RenderPassCreateInfo.h index 009dfecbe..32df3f362 100644 --- a/src/Magnum/Vk/RenderPassCreateInfo.h +++ b/src/Magnum/Vk/RenderPassCreateInfo.h @@ -566,6 +566,12 @@ class MAGNUM_VK_EXPORT SubpassDescription { * either @ref ImageLayout::General or @ref ImageLayout::ShaderReadOnly; * use a default-constructed @ref AttachmentReference to specify that * given input will be unused. + * + * The following @type_vk{SubpassDescription2} fields are set by this + * function: + * + * - `inputAttachmentCount` to @cpp attachments.size() @ce + * - `pInputAttachments` to a copy of @p attachments */ SubpassDescription& setInputAttachments(Containers::ArrayView attachments) &; /** @overload */ @@ -591,6 +597,14 @@ class MAGNUM_VK_EXPORT SubpassDescription { * @ref ImageLayout::ColorAttachment; use a default-constructed * @ref AttachmentReference to specify that given output will be * unused. + * + * The following @type_vk{SubpassDescription2} fields are set by this + * function: + * + * - `colorAttachmentCount` to @cpp attachments.size() @ce + * - `pColorAttachments` to a copy of @p attachments + * - `pResolveAttachments` to a copy of @p resolveAttachments, if + * the parameter is non-empty */ #ifdef DOXYGEN_GENERATING_OUTPUT SubpassDescription& setColorAttachments(Containers::ArrayView attachments, Containers::ArrayView resolveAttachments = {}) &; @@ -618,6 +632,11 @@ class MAGNUM_VK_EXPORT SubpassDescription { * with a default-constructed @ref AttachmentReference is equivalent to * not calling it at all, and both mean there's no depth/stencil * attachment. + * + * The following @type_vk{SubpassDescription2} fields are set by this + * function: + * + * - `pDepthStencilAttachment` to a copy of @p attachment */ SubpassDescription& setDepthStencilAttachment(AttachmentReference attachment) &; /** @overload */ @@ -631,6 +650,11 @@ class MAGNUM_VK_EXPORT SubpassDescription { * be preserved throughout the subpass. The @p attachment values are * indices into the list passed to * @ref RenderPassCreateInfo::setAttachments(). + * + * The following @type_vk{SubpassDescription2} fields are set by this + * function: + * + * - `pPreserveAttachments` to a copy of @p attachments */ SubpassDescription& setPreserveAttachments(Containers::ArrayView attachments) &; /** @overload */ @@ -966,6 +990,12 @@ class MAGNUM_VK_EXPORT RenderPassCreateInfo { * * Subsequent calls to this function will *replace* the previous set, * not append to it. + * + * The following @type_vk{RenderPassCreateInfo2} fields are set by this + * function: + * + * - `attachmentCount` to @cpp attachments.size() @ce + * - `pAttachments` to a copy of @p attachments */ RenderPassCreateInfo& setAttachments(Containers::ArrayView attachments); /** @overload */ @@ -984,6 +1014,16 @@ class MAGNUM_VK_EXPORT RenderPassCreateInfo { * to nested allocations inside @ref SubpassDescription, it's more * efficient to *move* the instances one by one than having to * deep-copy a list. + * + * The following @type_vk{RenderPassCreateInfo2} fields are set by this + * function: + * + * - `subpassCount` to the count of subpasses added previously by + * this function plus @cpp 1 @ce + * - `pSubpasses` to an array containing all subpass descriptions + * added previously by this function together with @p subpass; + * ownership of associated @ref SubpassDescription state is moved + * to the @ref RenderPassCreateInfo instance */ RenderPassCreateInfo& addSubpass(SubpassDescription&& subpass); @@ -991,8 +1031,14 @@ class MAGNUM_VK_EXPORT RenderPassCreateInfo { * @brief Set subpass dependencies * @return Reference to self (for method chaining) * - * ubsequent calls to this function will *replace* the previous set, + * Subsequent calls to this function will *replace* the previous set, * not append to it. + * + * The following @type_vk{RenderPassCreateInfo2} fields are set by this + * function: + * + * - `dependencyCount` to @cpp dependencies.size() @ce + * - `pDependencies` to a copy of @p dependencies */ RenderPassCreateInfo& setDependencies(Containers::ArrayView dependencies); /** @overload */