Update for Vulkan-Docs 1.2.140

include/vulkan/vulkan_beta.h

@@ -90,9 +90,6 @@ typedef enum VkAccelerationStructureBuildTypeKHR {
     VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR = 0,
     VK_ACCELERATION_STRUCTURE_BUILD_TYPE_DEVICE_KHR = 1,
     VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR = 2,
-    VK_ACCELERATION_STRUCTURE_BUILD_TYPE_BEGIN_RANGE_KHR = VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR,
-    VK_ACCELERATION_STRUCTURE_BUILD_TYPE_END_RANGE_KHR = VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR,
-    VK_ACCELERATION_STRUCTURE_BUILD_TYPE_RANGE_SIZE_KHR = (VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_OR_DEVICE_KHR - VK_ACCELERATION_STRUCTURE_BUILD_TYPE_HOST_KHR + 1),
     VK_ACCELERATION_STRUCTURE_BUILD_TYPE_MAX_ENUM_KHR = 0x7FFFFFFF
 } VkAccelerationStructureBuildTypeKHR;
 typedef union VkDeviceOrHostAddressKHR {

include/vulkan/vulkan_win32.h

@@ -272,9 +272,6 @@ typedef enum VkFullScreenExclusiveEXT {
     VK_FULL_SCREEN_EXCLUSIVE_ALLOWED_EXT = 1,
     VK_FULL_SCREEN_EXCLUSIVE_DISALLOWED_EXT = 2,
     VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT = 3,
-    VK_FULL_SCREEN_EXCLUSIVE_BEGIN_RANGE_EXT = VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT,
-    VK_FULL_SCREEN_EXCLUSIVE_END_RANGE_EXT = VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT,
-    VK_FULL_SCREEN_EXCLUSIVE_RANGE_SIZE_EXT = (VK_FULL_SCREEN_EXCLUSIVE_APPLICATION_CONTROLLED_EXT - VK_FULL_SCREEN_EXCLUSIVE_DEFAULT_EXT + 1),
     VK_FULL_SCREEN_EXCLUSIVE_MAX_ENUM_EXT = 0x7FFFFFFF
 } VkFullScreenExclusiveEXT;
 typedef struct VkSurfaceFullScreenExclusiveInfoEXT {

registry/cgenerator.py

@@ -126,6 +126,9 @@ def __init__(self,
         self.aliasMacro = aliasMacro
         """alias macro to inject when genAliasMacro is True"""
 
+        self.codeGenerator = True
+        """True if this generator makes compilable code"""
+
 
 class COutputGenerator(OutputGenerator):
     """Generates C-language API interfaces."""

registry/conventions.py

@@ -333,6 +333,13 @@ def generate_enum_table(self):
            group should be generated as part of group generation."""
         return False
 
+    @property
+    def generate_max_enum_in_docs(self):
+        """Return True if MAX_ENUM tokens should be generated in
+           documentation includes."""
+        return False
+
+
     def extension_include_string(self, ext):
         """Return format string for include:: line for an extension appendix
            file. ext is an object with the following members:

registry/generator.py

@@ -127,6 +127,7 @@ def __init__(self,
                  addExtensions=None,
                  removeExtensions=None,
                  emitExtensions=None,
+                 reparentEnums=True,
                  sortProcedure=regSortFeatures):
         """Constructor.
 
@@ -155,6 +156,11 @@ def __init__(self,
         - emitExtensions - regex matching names of extensions to actually emit
         interfaces for (though all requested versions are considered when
         deciding which interfaces to generate).
+        - reparentEnums - move <enum> elements which extend an enumerated
+        type from <feature> or <extension> elements to the target <enums>
+        element. This is required for almost all purposes, but the
+        InterfaceGenerator relies on the list of interfaces in the <feature>
+        or <extension> being complete. Defaults to True.
         - sortProcedure - takes a list of FeatureInfo objects and sorts
         them in place to a preferred order in the generated output.
         Default is core API versions, ARB/KHR/OES extensions, all other
@@ -208,12 +214,19 @@ def __init__(self,
         interfaces for (though all requested versions are considered when
         deciding which interfaces to generate)."""
 
+        self.reparentEnums = reparentEnums
+        """boolean specifying whether to remove <enum> elements from
+        <feature> or <extension> when extending an <enums> type."""
+
         self.sortProcedure = sortProcedure
         """takes a list of FeatureInfo objects and sorts
         them in place to a preferred order in the generated output.
         Default is core API versions, ARB/KHR/OES extensions, all
         other extensions, alphabetically within each group."""
 
+        self.codeGenerator = False
+        """True if this generator makes compilable code"""
+
     def emptyRegex(self, pat):
         """Substitute a regular expression which matches no version
         or extension names for None or the empty string."""
@@ -254,6 +267,7 @@ def __init__(self, errFile=sys.stderr, warnFile=sys.stderr, diagFile=sys.stdout)
         self.featureName = None
         self.genOpts = None
         self.registry = None
+        self.featureDictionary = {}
         # Used for extension enum value generation
         self.extBase = 1000000000
         self.extBlockSize = 1000
@@ -400,11 +414,9 @@ def checkDuplicateEnums(self, enums):
                 # still add this enum to the list.
                 (name2, numVal2, strVal2) = valueMap[numVal]
 
-                try:
-                    self.logMsg('warn', 'Two enums found with the same value: ' +
-                                name + ' = ' + name2.get('name') + ' = ' + strVal)
-                except:
-                    pdb.set_trace()
+                msg = 'Two enums found with the same value: {} = {} = {}'.format(
+                    name, name2.get('name'), strVal)
+                self.logMsg('error', msg)
 
             # Track this enum to detect followon duplicates
             nameMap[name] = [elem, numVal, strVal]
@@ -518,16 +530,19 @@ def buildEnumCDecl_Enum(self, expand, groupinfo, groupName):
         # Now append the non-numeric enumerant values
         body.extend(aliasText)
 
-        # Generate min/max value tokens and a range-padding enum. Need some
-        # additional padding to generate correct names...
+        # Generate min/max value tokens - legacy use case.
         if isEnum and expand:
             body.extend(("    {}_BEGIN_RANGE{} = {},".format(expandPrefix, expandSuffix, minName),
                          "    {}_END_RANGE{} = {},".format(
                              expandPrefix, expandSuffix, maxName),
                          "    {}_RANGE_SIZE{} = ({} - {} + 1),".format(expandPrefix, expandSuffix, maxName, minName)))
 
-        body.append("    {}_MAX_ENUM{} = 0x7FFFFFFF".format(
-            expandPrefix, expandSuffix))
+        # Generate a range-padding value to ensure the enum is 32 bits, but
+        # only in code generators, so it doesn't appear in documentation
+        if (self.genOpts.codeGenerator or
+            self.conventions.generate_max_enum_in_docs):
+            body.append("    {}_MAX_ENUM{} = 0x7FFFFFFF".format(
+                expandPrefix, expandSuffix))
 
         # Postfix
         body.append("} %s;" % groupName)

registry/genvk.py

@@ -25,9 +25,11 @@
 from docgenerator import DocGeneratorOptions, DocOutputGenerator
 from extensionmetadocgenerator import (ExtensionMetaDocGeneratorOptions,
                                        ExtensionMetaDocOutputGenerator)
+from interfacedocgenerator import InterfaceDocGenerator
 from generator import write
 from hostsyncgenerator import HostSynchronizationOutputGenerator
 from pygenerator import PyOutputGenerator
+from reflib import logDiag, logWarn, setLogFile
 from reg import Registry
 from validitygenerator import ValidityOutputGenerator
 from vkconventions import VulkanConventions
@@ -47,7 +49,7 @@ def endTimer(timeit, msg):
     global startTime
     if timeit:
         endTime = time.process_time()
-        write(msg, endTime - startTime, file=sys.stderr)
+        logDiag(msg, endTime - startTime)
         startTime = None
 
 
@@ -212,10 +214,14 @@ def makeGenOpts(args):
             defaultExtensions = None,
             addExtensions     = addExtensionsPat,
             removeExtensions  = removeExtensionsPat,
-            emitExtensions    = emitExtensionsPat)
+            emitExtensions    = emitExtensionsPat,
+            reparentEnums     = False)
         ]
 
     # Extension metainformation for spec extension appendices
+    # Includes all extensions by default, but only so that the generated
+    # 'promoted_extensions_*' files refer to all extensions that were
+    # promoted to a core version.
     genOpts['extinc'] = [
           ExtensionMetaDocOutputGenerator,
           ExtensionMetaDocGeneratorOptions(
@@ -227,11 +233,30 @@ def makeGenOpts(args):
             versions          = featuresPat,
             emitversions      = None,
             defaultExtensions = defaultExtensions,
-            addExtensions     = None,
+            addExtensions     = addExtensionsPat,
             removeExtensions  = None,
             emitExtensions    = emitExtensionsPat)
         ]
 
+    # Version and extension interface docs for version/extension appendices
+    # Includes all extensions by default.
+    genOpts['interfaceinc'] = [
+          InterfaceDocGenerator,
+          DocGeneratorOptions(
+            conventions       = conventions,
+            filename          = 'timeMarker',
+            directory         = directory,
+            apiname           = 'vulkan',
+            profile           = None,
+            versions          = featuresPat,
+            emitversions      = featuresPat,
+            defaultExtensions = None,
+            addExtensions     = addExtensionsPat,
+            removeExtensions  = removeExtensionsPat,
+            emitExtensions    = emitExtensionsPat,
+            reparentEnums     = False)
+        ]
+
     # Platform extensions, in their own header files
     # Each element of the platforms[] array defines information for
     # generating a single platform:
@@ -313,8 +338,7 @@ def makeGenOpts(args):
             apicall           = 'VKAPI_ATTR ',
             apientry          = 'VKAPI_CALL ',
             apientryp         = 'VKAPI_PTR *',
-            alignFuncParam    = 48,
-            genEnumBeginEndRange = True)
+            alignFuncParam    = 48)
 
         genOpts[headername] = [ COutputGenerator, opts ]
 
@@ -352,8 +376,7 @@ def makeGenOpts(args):
             apicall           = 'VKAPI_ATTR ',
             apientry          = 'VKAPI_CALL ',
             apientryp         = 'VKAPI_PTR *',
-            alignFuncParam    = 48,
-            genEnumBeginEndRange = True)
+            alignFuncParam    = 48)
         ]
 
     # Unused - vulkan10.h target.
@@ -415,7 +438,8 @@ def makeGenOpts(args):
 
 
 def genTarget(args):
-    """Generate a target based on the options in the matching genOpts{} object.
+    """Create an API generator and corresponding generator options based on
+    the requested target and command line options.
 
     This is encapsulated in a function so it can be profiled and/or timed.
     The args parameter is an parsed argument object containing the following
@@ -425,35 +449,30 @@ def genTarget(args):
     - directory - directory to generate it in
     - protect - True if re-inclusion wrappers should be created
     - extensions - list of additional extensions to include in generated interfaces"""
-    # Create generator options with specified parameters
+
+    # Create generator options with parameters specified on command line
     makeGenOpts(args)
 
+    # Select a generator matching the requested target
     if args.target in genOpts:
         createGenerator = genOpts[args.target][0]
         options = genOpts[args.target][1]
 
-        if not args.quiet:
-            write('* Building', options.filename, file=sys.stderr)
-            write('* options.versions          =', options.versions, file=sys.stderr)
-            write('* options.emitversions      =', options.emitversions, file=sys.stderr)
-            write('* options.defaultExtensions =', options.defaultExtensions, file=sys.stderr)
-            write('* options.addExtensions     =', options.addExtensions, file=sys.stderr)
-            write('* options.removeExtensions  =', options.removeExtensions, file=sys.stderr)
-            write('* options.emitExtensions    =', options.emitExtensions, file=sys.stderr)
+        logDiag('* Building', options.filename)
+        logDiag('* options.versions          =', options.versions)
+        logDiag('* options.emitversions      =', options.emitversions)
+        logDiag('* options.defaultExtensions =', options.defaultExtensions)
+        logDiag('* options.addExtensions     =', options.addExtensions)
+        logDiag('* options.removeExtensions  =', options.removeExtensions)
+        logDiag('* options.emitExtensions    =', options.emitExtensions)
 
-        startTimer(args.time)
         gen = createGenerator(errFile=errWarn,
                               warnFile=errWarn,
                               diagFile=diag)
-        reg.setGenerator(gen)
-        reg.apiGen(options)
-
-        if not args.quiet:
-            write('* Generated', options.filename, file=sys.stderr)
-        endTimer(args.time, '* Time to generate ' + options.filename + ' =')
+        return (gen, options)
     else:
-        write('No generator options for unknown target:',
-              args.target, file=sys.stderr)
+        logErr('No generator options for unknown target:', args.target)
+        return None
 
 
 # -feature name
@@ -515,45 +534,48 @@ def genTarget(args):
     args.feature = [name for arg in args.feature for name in arg.split()]
     args.extension = [name for arg in args.extension for name in arg.split()]
 
-    # Load & parse registry
-    reg = Registry()
+    # create error/warning & diagnostic files
+    if args.errfile:
+        errWarn = open(args.errfile, 'w', encoding='utf-8')
+    else:
+        errWarn = sys.stderr
+
+    if args.diagfile:
+        diag = open(args.diagfile, 'w', encoding='utf-8')
+    else:
+        diag = None
+
+    # Create the API generator & generator options
+    (gen, options) = genTarget(args)
 
+    # Create the registry object with the specified generator and generator
+    # options. The options are set before XML loading as they may affect it.
+    reg = Registry(gen, options)
+
+    # Parse the specified registry XML into an ElementTree object
     startTimer(args.time)
     tree = etree.parse(args.registry)
     endTimer(args.time, '* Time to make ElementTree =')
 
-    if args.debug:
-        pdb.run('reg.loadElementTree(tree)')
-    else:
-        startTimer(args.time)
-        reg.loadElementTree(tree)
-        endTimer(args.time, '* Time to parse ElementTree =')
+    # Load the XML tree into the registry object
+    startTimer(args.time)
+    reg.loadElementTree(tree)
+    endTimer(args.time, '* Time to parse ElementTree =')
 
     if args.validate:
         reg.validateGroups()
 
     if args.dump:
-        write('* Dumping registry to regdump.txt', file=sys.stderr)
+        logDiag('* Dumping registry to regdump.txt')
         reg.dumpReg(filehandle=open('regdump.txt', 'w', encoding='utf-8'))
 
-    # create error/warning & diagnostic files
-    if args.errfile:
-        errWarn = open(args.errfile, 'w', encoding='utf-8')
-    else:
-        errWarn = sys.stderr
-
-    if args.diagfile:
-        diag = open(args.diagfile, 'w', encoding='utf-8')
-    else:
-        diag = None
-
+    # Finally, use the output generator to create the requested target
     if args.debug:
-        pdb.run('genTarget(args)')
-    elif args.profile:
-        import cProfile
-        import pstats
-        cProfile.run('genTarget(args)', 'profile.txt')
-        p = pstats.Stats('profile.txt')
-        p.strip_dirs().sort_stats('time').print_stats(50)
+        pdb.run('reg.apiGen()')
     else:
-        genTarget(args)
+        startTimer(args.time)
+        reg.apiGen()
+        endTimer(args.time, '* Time to generate ' + options.filename + ' =')
+
+    if not args.quiet:
+        logDiag('* Generated', options.filename)