Merge pull request #646 from asuessenbach/DesignatedInitializers

Introduce VULKAN_HPP_NO_STRUCT_CONSTRUCTORS to support designated initializers.

CMakeLists.txt

@@ -53,7 +53,7 @@ else(MSVC)
   add_compile_options(-Wall)
 endif(MSVC)
 
-set(CMAKE_CXX_STANDARD 14)
+set(CMAKE_CXX_STANDARD 11)
 
 if (NOT DEFINED VULKAN_HPP_VULKAN_HEADERS_SRC_DIR)
   set(VULKAN_HPP_VULKAN_HEADERS_SRC_DIR "${CMAKE_CURRENT_SOURCE_DIR}/Vulkan-Headers")

README.md

@@ -115,6 +115,31 @@ vk::Image image = device.createImage({{}, vk::ImageType::e2D, vk::format::eR8G8B
                                      vk::SharingMode::eExclusive, 0, 0, vk::Imagelayout::eUndefined});
 ```
 
+### Designated Initializers
+
+Beginning with C++20, C++ supports designated initializers. As that feature requires to not have any user-declared or inherited constructors, you have to `#define VULKAN_HPP_NO_STRUCT_CONSTRUCTORS`, which removes all the structure constructors from vulkan.hpp. Instead you can then use aggregate initialization. The first few vk-lines in your source might then look like
+```
+// initialize the vk::ApplicationInfo structure
+vk::ApplicationInfo applicationInfo{ .pApplicationName   = AppName,
+                                     .applicationVersion = 1,
+                                     .pEngineName        = EngineName,
+                                     .engineVersion      = 1,
+                                     .apiVersion         = VK_API_VERSION_1_1 };
+        
+// initialize the vk::InstanceCreateInfo
+vk::InstanceCreateInfo instanceCreateInfo{ .pApplicationInfo = & applicationInfo };
+```
+instead of
+```
+// initialize the vk::ApplicationInfo structure
+vk::ApplicationInfo applicationInfo( AppName, 1, EngineName, 1, VK_API_VERSION_1_1 );
+        
+// initialize the vk::InstanceCreateInfo
+vk::InstanceCreateInfo instanceCreateInfo( {}, &applicationInfo );
+```
+Note, that the designator order needs to match the declaration order.
+Note as well, that now you can explicitly set the sType member of vk-structures. This is neither neccessary (as they are correctly initialized by default) nor recommended.
+
 ### Passing Arrays to Functions using ArrayProxy
 
 The Vulkan API has several places where which require (count,pointer) as two function arguments and C++ has a few containers which map perfectly to this pair. To simplify development the Vulkan-Hpp bindings have replaced those argument pairs with the `ArrayProxy` template class which accepts empty arrays and a single value as well as STL containers `std::initializer_list`, `std::array` and `std::vector` as argument for construction. This way a single generated Vulkan version can accept a variety of inputs without having the combinatoric explosion which would occur when creating a function for each container type.

VulkanHppGenerator.cpp

@@ -3464,10 +3464,20 @@ void VulkanHppGenerator::appendStruct( std::string &
   }
 }
 
-void VulkanHppGenerator::appendStructAssignmentOperator( std::string &                                 str,
+void VulkanHppGenerator::appendStructAssignmentOperators( std::string &                                 str,
-                                                         std::pair<std::string, StructureData> const & structData,
+                                                          std::pair<std::string, StructureData> const & structData,
-                                                         std::string const &                           prefix ) const
+                                                          std::string const &                           prefix ) const
 {
+  static const std::string assignmentFromVulkanType = R"(
+${prefix}${structName} & operator=( Vk${structName} const & rhs ) VULKAN_HPP_NOEXCEPT
+${prefix}{
+${prefix}  *this = *reinterpret_cast<VULKAN_HPP_NAMESPACE::${structName} const *>( &rhs );
+${prefix}  return *this;
+${prefix}}
+)";
+  str += replaceWithMap( assignmentFromVulkanType,
+                         { { "prefix", prefix }, { "structName", stripPrefix( structData.first, "Vk" ) } } );
+
   // we need an assignment operator if there is constant sType in this struct
   std::string copyTemplate;
   if ( ( nonConstSTypeStructs.find( structData.first ) == nonConstSTypeStructs.end() ) &&
@@ -3548,14 +3558,22 @@ std::string
            : "";
 }
 
-void VulkanHppGenerator::appendStructConstructor( std::string &                                 str,
+void VulkanHppGenerator::appendStructConstructors( std::string &                                 str,
-                                                  std::pair<std::string, StructureData> const & structData,
+                                                   std::pair<std::string, StructureData> const & structData,
-                                                  std::string const &                           prefix ) const
+                                                   std::string const &                           prefix ) const
 {
   // the constructor with all the elements as arguments, with defaults
-  std::string constexprString = constructConstexprString( structData );
+  // and the simple copy constructor from the corresponding vulkan structure
-  std::string ctorOpening     = prefix + constexprString + stripPrefix( structData.first, "Vk" );
+  static const std::string constructors = R"(
-  std::string indentation( ctorOpening.size() + 2, ' ' );
+${prefix}${constexpr}${structName}(${arguments}) VULKAN_HPP_NOEXCEPT
+${prefix}${initializers}
+${prefix}{}
+
+${prefix}${structName}( Vk${structName} const & rhs ) VULKAN_HPP_NOEXCEPT
+${prefix}{
+${prefix}  *this = rhs;
+${prefix}}
+)";
 
   std::string arguments, initializers;
   bool        listedArgument = false;
@@ -3563,29 +3581,32 @@ void VulkanHppGenerator::appendStructConstructor( std::string &
   for ( auto const & member : structData.second.members )
   {
     // gather the arguments
-    listedArgument = appendStructConstructorArgument( arguments, listedArgument, indentation, member );
+    listedArgument = appendStructConstructorArgument( arguments, listedArgument, member );
 
     // gather the initializers; skip members 'pNext' and 'sType', they are directly set by initializers
     if ( ( member.name != "pNext" ) && ( member.name != "sType" ) )
     {
-      initializers += prefix + "  " + ( firstArgument ? ":" : "," ) + " " + member.name + "( " + member.name + "_ )\n";
+      initializers += ( firstArgument ? ":" : "," ) + std::string( " " ) + member.name + "( " + member.name + "_ )";
       firstArgument = false;
     }
   }
 
-  str += ctorOpening + ( arguments.empty() ? "()" : std::string( "( " + arguments + " )" ) ) +
+  str += replaceWithMap( constructors,
-         " VULKAN_HPP_NOEXCEPT\n" + initializers + prefix + "{}\n";
+                         { { "arguments", arguments },
+                           { "constexpr", constructConstexprString( structData ) },
+                           { "initializers", initializers },
+                           { "prefix", prefix },
+                           { "structName", stripPrefix( structData.first, "Vk" ) } } );
 }
 
-bool VulkanHppGenerator::appendStructConstructorArgument( std::string &       str,
+bool VulkanHppGenerator::appendStructConstructorArgument( std::string &      str,
-                                                          bool                listedArgument,
+                                                          bool               listedArgument,
-                                                          std::string const & indentation,
+                                                          MemberData const & memberData ) const
-                                                          MemberData const &  memberData ) const
 {
   // skip members 'pNext' and 'sType', as they are never explicitly set
   if ( ( memberData.name != "pNext" ) && ( memberData.name != "sType" ) )
   {
-    str += ( listedArgument ? ( ",\n" + indentation ) : "" );
+    str += ( listedArgument ? ( "," ) : "" );
     if ( memberData.arraySizes.empty() )
     {
       str += memberData.type.compose() + " ";
@@ -3611,24 +3632,6 @@ bool VulkanHppGenerator::appendStructConstructorArgument( std::string &       st
   return listedArgument;
 }
 
-void VulkanHppGenerator::appendStructCopyConstructors( std::string & str, std::string const & name ) const
-{
-  static const std::string templateString = R"(
-    ${name}( Vk${name} const & rhs ) VULKAN_HPP_NOEXCEPT
-    {
-      *this = rhs;
-    }
-
-    ${name}& operator=( Vk${name} const & rhs ) VULKAN_HPP_NOEXCEPT
-    {
-      *this = *reinterpret_cast<VULKAN_HPP_NAMESPACE::${name} const *>(&rhs);
-      return *this;
-    }
-)";
-
-  str += replaceWithMap( templateString, { { "name", name } } );
-}
-
 std::string VulkanHppGenerator::appendStructMembers( std::string &                                 str,
                                                      std::pair<std::string, StructureData> const & structData,
                                                      std::string const &                           prefix ) const
@@ -3791,8 +3794,7 @@ void VulkanHppGenerator::appendStructSubConstructor( std::string &
     bool        listedArgument = true;
     for ( size_t i = subStruct->second.members.size(); i < structData.second.members.size(); i++ )
     {
-      listedArgument =
+      listedArgument = appendStructConstructorArgument( subArguments, listedArgument, structData.second.members[i] );
-        appendStructConstructorArgument( subArguments, listedArgument, indentation, structData.second.members[i] );
 
       assert( structData.second.members[i].arraySizes.empty() );
       subCopies +=
@@ -3816,10 +3818,11 @@ void VulkanHppGenerator::appendStructure( std::string &
   str += "\n" + enter;
 
   std::string constructorAndSetters;
-  appendStructConstructor( constructorAndSetters, structure, "    " );
+  constructorAndSetters += "#if !defined( VULKAN_HPP_NO_STRUCT_CONSTRUCTORS )";
+  appendStructConstructors( constructorAndSetters, structure, "    " );
   appendStructSubConstructor( constructorAndSetters, structure, "    " );
-  appendStructAssignmentOperator( constructorAndSetters, structure, "    " );
+  constructorAndSetters += "#endif // !defined( VULKAN_HPP_NO_STRUCT_CONSTRUCTORS )\n";
-  appendStructCopyConstructors( constructorAndSetters, stripPrefix( structure.first, "Vk" ) );
+  appendStructAssignmentOperators( constructorAndSetters, structure, "    " );
   if ( !structure.second.returnedOnly )
   {
     // only structs that are not returnedOnly get setters!
@@ -7904,16 +7907,16 @@ int main( int argc, char ** argv )
 #  define VULKAN_HPP_CPLUSPLUS __cplusplus
 #endif
 
-#if VULKAN_HPP_CPLUSPLUS < 201103L
+#if 201703L < VULKAN_HPP_CPLUSPLUS
-static_assert( false, "vulkan.hpp needs at least c++ standard version 11" );
-#elif VULKAN_HPP_CPLUSPLUS < 201402L
-#  define VULKAN_HPP_CPP_VERSION 11
-#elif VULKAN_HPP_CPLUSPLUS < 201703L
-#  define VULKAN_HPP_CPP_VERSION 14
-#elif VULKAN_HPP_CPLUSPLUS < 202002L
-#  define VULKAN_HPP_CPP_VERSION 17
-#else
 #  define VULKAN_HPP_CPP_VERSION 20
+#elif 201402L < VULKAN_HPP_CPLUSPLUS
+#  define VULKAN_HPP_CPP_VERSION 17
+#elif 201103L < VULKAN_HPP_CPLUSPLUS
+#  define VULKAN_HPP_CPP_VERSION 14
+#elif 199711L < VULKAN_HPP_CPLUSPLUS
+#  define VULKAN_HPP_CPP_VERSION 11
+#else
+#  error "vulkan.hpp needs at least c++ standard version 11"
 #endif
 
 #include <algorithm>

VulkanHppGenerator.hpp

@@ -470,18 +470,14 @@ private:
   void appendStruct( std::string &                                 str,
                      std::pair<std::string, StructureData> const & structure,
                      std::set<std::string> &                       listedStructures ) const;
-  void appendStructAssignmentOperator( std::string &                                 str,
+  void appendStructAssignmentOperators( std::string &                                 str,
-                                       std::pair<std::string, StructureData> const & structure,
+                                        std::pair<std::string, StructureData> const & structure,
-                                       std::string const &                           prefix ) const;
+                                        std::string const &                           prefix ) const;
   void appendStructCompareOperators( std::string & str, std::pair<std::string, StructureData> const & structure ) const;
-  void appendStructConstructor( std::string &                                 str,
+  void appendStructConstructors( std::string &                                 str,
-                                std::pair<std::string, StructureData> const & structData,
+                                 std::pair<std::string, StructureData> const & structData,
-                                std::string const &                           prefix ) const;
+                                 std::string const &                           prefix ) const;
-  bool appendStructConstructorArgument( std::string &       str,
+  bool appendStructConstructorArgument( std::string & str, bool listedArgument, MemberData const & memberData ) const;
-                                        bool                listedArgument,
-                                        std::string const & indentation,
-                                        MemberData const &  memberData ) const;
-  void appendStructCopyConstructors( std::string & str, std::string const & vkName ) const;
   std::string appendStructMembers( std::string &                                 str,
                                    std::pair<std::string, StructureData> const & structData,
                                    std::string const &                           prefix ) const;

tests/DesignatedInitializers/CMakeLists.txt

@@ -0,0 +1,39 @@
+# Copyright(c) 2020, NVIDIA CORPORATION. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+cmake_minimum_required(VERSION 3.2)
+
+if (NOT TESTS_BUILD_ONLY_DYNAMIC)
+	project(DesignatedInitializers)
+
+    set(CMAKE_CXX_STANDARD 20)
+
+	set(HEADERS
+	)
+
+	set(SOURCES
+	  DesignatedInitializers.cpp
+	)
+
+	source_group(headers FILES ${HEADERS})
+	source_group(sources FILES ${SOURCES})
+
+	add_executable(DesignatedInitializers
+	  ${HEADERS}
+	  ${SOURCES}
+	)
+
+	set_target_properties(DesignatedInitializers PROPERTIES FOLDER "Tests")
+	target_link_libraries(DesignatedInitializers "${Vulkan_LIBRARIES}")
+endif()

tests/DesignatedInitializers/DesignatedInitializers.cpp

@@ -0,0 +1,70 @@
+// Copyright(c) 2020, NVIDIA CORPORATION. All rights reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// VulkanHpp Tests : DesignatedInitializers
+//                   Compile test on using designated initializers
+
+#define VULKAN_HPP_NO_STRUCT_CONSTRUCTORS
+
+#include "vulkan/vulkan.hpp"
+
+#include <iostream>
+
+int main( int /*argc*/, char ** /*argv*/ )
+{
+  char const * appName       = "DesignatedInitializers";
+  uint32_t     appVersion    = 1;
+  char const * engineName    = "Vulkan.hpp";
+  uint32_t     engineVersion = 1;
+
+  // default initialization is available in any case
+  vk::ApplicationInfo ai0;
+
+#if !defined( VULKAN_HPP_NO_STRUCT_CONSTRUCTORS )
+  // due to default initializers, any number of members can be initialized
+  // most IDEs will probably help with the order of the members !
+  vk::ApplicationInfo ai1( appName );
+  vk::ApplicationInfo ai2( appName, appVersion );
+  vk::ApplicationInfo ai3( appName, appVersion, engineName );
+  vk::ApplicationInfo ai4( appName, appVersion, engineName, engineVersion );
+  vk::ApplicationInfo ai5( appName, appVersion, engineName, engineVersion, VK_API_VERSION_1_2 );
+
+  // a structure in namespace vk:: can be copied from the corresponding vulkan C-struct
+  VkApplicationInfo   vai;
+  vk::ApplicationInfo ai6( vai );
+
+#else
+
+  // aggregate initialization: need to explicitly specify sType and pNext, as well as all the other members !
+  vk::ApplicationInfo ai1{
+    vk::StructureType::eApplicationInfo, nullptr, appName, appVersion, engineName, engineVersion, VK_API_VERSION_1_2
+  };
+
+#  if ( 20 <= VULKAN_HPP_CPP_VERSION )
+  // designated initializers are available with C++20
+
+  // it's allowed, but not recommended to explicitly specify sType
+  vk::ApplicationInfo ai2 = { .sType = vk::StructureType::eApplicationInfo };
+
+  // any number of the members can be specified; the order has to be respected
+  vk::ApplicationInfo ai3 = { .pApplicationName = appName };
+  vk::ApplicationInfo ai4 = { .applicationVersion = 1, .engineVersion = 2 };
+
+  vk::ApplicationInfo ai5{ .pEngineName = engineName };
+  vk::ApplicationInfo ai6{ .pApplicationName = appName, .apiVersion = VK_API_VERSION_1_2 };
+#  endif
+#endif
+
+  return 0;
+}