def endFile(self):
# Print out all the dictionaries as Python strings.
# Could just print(dict) but that's not human-readable
dicts = ([self.basetypes,
'basetypes'], [self.consts, 'consts'], [self.enums, 'enums'],
[self.flags, 'flags'], [self.funcpointers, 'funcpointers'],
[self.protos,
'protos'], [self.structs,
'structs'], [self.handles, 'handles'],
[self.defines,
'defines'], [self.typeCategory,
'typeCategory'], [self.alias, 'alias'])
for (entry_dict, name) in dicts:
write(name + ' = {}', file=self.outFile)
for key in sorted(entry_dict.keys()):
write(name + '[' + enquote(key) + '] = ',
entry_dict[key],
file=self.outFile)
# Dictionary containing the relationships of a type
# (e.g. a dictionary with each related type as keys).
write('mapDict = {}', file=self.outFile)
# Could just print(self.mapDict), but prefer something
# human-readable and stable-ordered
for baseType in sorted(self.mapDict.keys()):
write('mapDict[' + enquote(baseType) + '] = ',
file=self.outFile,
end='')
pprint(self.mapDict[baseType], self.outFile)
OutputGenerator.endFile(self)
def endFile(self):
# Print out all the dictionaries as Python strings.
# Could just print(dict) but that's not human-readable
dicts = [ [ self.basetypes, 'basetypes' ],
[ self.consts, 'consts' ],
[ self.enums, 'enums' ],
[ self.flags, 'flags' ],
[ self.funcpointers, 'funcpointers' ],
[ self.protos, 'protos' ],
[ self.structs, 'structs' ],
[ self.handles, 'handles' ],
[ self.defines, 'defines' ],
[ self.typeCategory, 'typeCategory' ],
[ self.alias, 'alias' ],
]
for (entry_dict, name) in dicts:
write(name + ' = {}', file=self.outFile)
for key in sorted(entry_dict.keys()):
write(name + '[' + enquote(key) + '] = ', entry_dict[key],
file=self.outFile)
# Dictionary containing the relationships of a type
# (e.g. a dictionary with each related type as keys).
write('mapDict = {}', file=self.outFile)
# Could just print(self.mapDict), but prefer something
# human-readable and stable-ordered
for baseType in sorted(self.mapDict.keys()):
write('mapDict[' + enquote(baseType) + '] = ', file=self.outFile, end='')
pprint(self.mapDict[baseType], self.outFile)
OutputGenerator.endFile(self)
def endFile(self):
# Remove things from enums if they're a flag bits.
flag_bits = set(self.enums.keys()).intersection(self.flags.values())
for f in flag_bits:
self.enums.pop(f)
# This sets up the sub-chapter order
pieces = (
('Base Types and Atoms', self.basetypes, 'basetype:'),
('Defines', self.defines, 'dlink:'),
('Enumerations', self.enums, 'elink:'),
('Flags and Flag Bits', self.flags, 'elink:'),
('Function Pointer Types', self.funcpointers, 'tlink:'),
('Functions', self.protos, 'flink:'),
('Handles', self.handles, 'slink:'),
('Structures', self.structs, 'slink:'),
)
write('[[index]]', file=self.outFile)
write('## Index', file=self.outFile)
write('', file=self.outFile)
for title, name_dict, prefix in pieces:
self.output_name_dict(name_dict, title, prefix)
OutputGenerator.endFile(self)
def endFile(self):
for pointer in self.pointers:
write(pointer, file=self.outFile)
self.newline()
write('void vkExtInitInstance(VkInstance instance)\n{',
file=self.outFile)
for pointerInitializer in self.pointerInitializersInstance:
write(pointerInitializer, file=self.outFile)
write('}', file=self.outFile)
self.newline()
write('void vkExtInitDevice(VkDevice device)\n{', file=self.outFile)
for pointerInitializer in self.pointerInitializersDevice:
write(pointerInitializer, file=self.outFile)
write('}', file=self.outFile)
self.newline()
#Finish header file
write('#ifdef __cplusplus', file=self.outFileHeader)
write('}', file=self.outFileHeader)
write('#endif', file=self.outFileHeader)
write('', file=self.outFileHeader)
write('#endif', file=self.outFileHeader)
self.outFileHeader.close()
# Finish processing in superclass
OutputGenerator.endFile(self)
def endFile(self):
file_data = ''
unprotected_structs = self.getStructsForProtect()
protected_structs = [(x, self.getStructsForProtect(x))
for x in sorted(self.protects)]
extensions = list(((name, data)
for name, data in self.registry.extdict.items()
if data.supported != 'disabled'))
def getNumber(x):
return int(x[1].number)
extensions.sort(key=getNumber)
file_data += self.template.render(
unprotectedStructs=unprotected_structs,
protectedStructs=protected_structs,
structs=self.structs,
enums=self.enums,
bitmasks=self.bitmasks,
extensions=extensions)
write(file_data, file=self.outFile)
# Finish processing in superclass
OutputGenerator.endFile(self)
def endFile(self):
# Finish C++ wrapper and multiple inclusion protection
if (self.genOpts.protectFile and self.genOpts.filename):
self.newline()
write('#endif', file=self.outFile)
# Finish processing in superclass
OutputGenerator.endFile(self)
def endFile(self):
# C-specific
# Finish C++ wrapper and multiple inclusion protection
self.newline()
write('#ifdef __cplusplus', file=self.outFile)
write('}', file=self.outFile)
write('#endif', file=self.outFile)
if self.genOpts.protectFile and self.genOpts.filename:
self.newline()
write('#endif', file=self.outFile)
# Finish processing in superclass
OutputGenerator.endFile(self)
def endFile(self):
# C-specific
# Finish C++ wrapper and multiple inclusion protection
self.newline()
write('#ifdef __cplusplus', file=self.outFile)
write('}', file=self.outFile)
write('#endif', file=self.outFile)
if self.genOpts.protectFile and self.genOpts.filename:
self.newline()
write('#endif', file=self.outFile)
# Finish processing in superclass
OutputGenerator.endFile(self)
def endFile(self):
# Print out all the dictionaries as Python strings.
# Could just print(dict) but that's not human-readable
dicts = ([self.basetypes,
'basetypes'], [self.consts, 'consts'], [self.enums, 'enums'],
[self.flags, 'flags'], [self.funcpointers, 'funcpointers'],
[self.protos,
'protos'], [self.structs,
'structs'], [self.handles, 'handles'],
[self.defines,
'defines'], [self.typeCategory,
'typeCategory'], [self.alias, 'alias'])
for (entry_dict, name) in dicts:
write(name + ' = {}', file=self.outFile)
for key in sorted(entry_dict.keys()):
write(name + '[' + enquote(key) + '] = ',
entry_dict[key],
file=self.outFile)
# Dictionary containing the relationships of a type
# (e.g. a dictionary with each related type as keys).
write('mapDict = {}', file=self.outFile)
# Could just print(self.mapDict), but prefer something
# human-readable and stable-ordered
for baseType in sorted(self.mapDict.keys()):
write('mapDict[' + enquote(baseType) + '] = ',
file=self.outFile,
end='')
pprint.pprint(self.mapDict[baseType], self.outFile)
# Generate feature <-> interface mappings
for feature in self.features:
self.mapInterfaces(feature)
# Write out the reverse map from APIs to requiring features
write('requiredBy = {}', file=self.outFile)
for api in sorted(self.apimap):
# Construct list of requirements as Python list arguments
##reqs = ', '.join('({}, {})'.format(enquote(dep[0]), enquote(dep[1])) for dep in self.apimap[api])
##write('requiredBy[{}] = ( {} )'.format(enquote(api), reqs), file=self.outFile)
# Ideally these would be sorted by dep[0] as well
reqs = ', '.join(
'({}, {})'.format(enquote(dep[0]), enquote(dep[1]))
for dep in self.apimap[api])
write('requiredBy[{}] = {}'.format(
enquote(api), pprint.saferepr(self.apimap[api])),
file=self.outFile)
OutputGenerator.endFile(self)
def endFile(self):
file_data = ''
try:
file_data += self.template.render(structs=self.structs,
enums=self.enums,
bitmasks=self.bitmasks)
except TemplateSyntaxError as e:
print("{}:{} error: {}".format(e.filename, e.lineno, e.message))
raise e
write(file_data, file=self.outFile)
# Finish processing in superclass
OutputGenerator.endFile(self)
class Registry:
"""Represents an API registry loaded from XML"""
def __init__(self):
self.tree = None
self.typedict = {}
self.groupdict = {}
self.enumdict = {}
self.cmddict = {}
self.apidict = {}
self.extensions = []
self.extdict = {}
# A default output generator, so commands prior to apiGen can report
# errors via the generator object.
self.gen = OutputGenerator()
self.genOpts = None
self.emitFeatures = False
def loadElementTree(self, tree):
"""Load ElementTree into a Registry object and parse it"""
self.tree = tree
self.parseTree()
def loadFile(self, file):
"""Load an API registry XML file into a Registry object and parse it"""
self.tree = etree.parse(file)
self.parseTree()
def setGenerator(self, gen):
"""Specify output generator object. None restores the default generator"""
self.gen = gen
self.gen.setRegistry(self)
# addElementInfo - add information about an element to the
# corresponding dictionary
# elem - <type>/<enums>/<enum>/<command>/<feature>/<extension> Element
# info - corresponding {Type|Group|Enum|Cmd|Feature}Info object
# infoName - 'type' / 'group' / 'enum' / 'command' / 'feature' / 'extension'
# dictionary - self.{type|group|enum|cmd|api|ext}dict
# If the Element has an 'api' attribute, the dictionary key is the
# tuple (name,api). If not, the key is the name. 'name' is an
# attribute of the Element
def addElementInfo(self, elem, info, infoName, dictionary):
if ('api' in elem.attrib):
key = (elem.get('name'), elem.get('api'))
else:
key = elem.get('name')
if key in dictionary:
self.gen.logMsg('warn', '*** Attempt to redefine', infoName,
'with key:', key)
else:
dictionary[key] = info
#
# lookupElementInfo - find a {Type|Enum|Cmd}Info object by name.
# If an object qualified by API name exists, use that.
# fname - name of type / enum / command
# dictionary - self.{type|enum|cmd}dict
def lookupElementInfo(self, fname, dictionary):
key = (fname, self.genOpts.apiname)
if (key in dictionary):
# self.gen.logMsg('diag', 'Found API-specific element for feature', fname)
return dictionary[key]
elif (fname in dictionary):
# self.gen.logMsg('diag', 'Found generic element for feature', fname)
return dictionary[fname]
else:
return None
def parseTree(self):
"""Parse the registry Element, once created"""
# This must be the Element for the root <registry>
self.reg = self.tree.getroot()
#
# Create dictionary of registry types from toplevel <types> tags
# and add 'name' attribute to each <type> tag (where missing)
# based on its <name> element.
#
# There's usually one <types> block; more are OK
# Required <type> attributes: 'name' or nested <name> tag contents
self.typedict = {}
for type in self.reg.findall('types/type'):
# If the <type> doesn't already have a 'name' attribute, set
# it from contents of its <name> tag.
if (type.get('name') == None):
type.attrib['name'] = type.find('name').text
self.addElementInfo(type, TypeInfo(type), 'type', self.typedict)
#
# Create dictionary of registry enum groups from <enums> tags.
#
# Required <enums> attributes: 'name'. If no name is given, one is
# generated, but that group can't be identified and turned into an
# enum type definition - it's just a container for <enum> tags.
self.groupdict = {}
for group in self.reg.findall('enums'):
self.addElementInfo(group, GroupInfo(group), 'group',
self.groupdict)
#
# Create dictionary of registry enums from <enum> tags
#
# <enums> tags usually define different namespaces for the values
# defined in those tags, but the actual names all share the
# same dictionary.
# Required <enum> attributes: 'name', 'value'
# For containing <enums> which have type="enum" or type="bitmask",
# tag all contained <enum>s are required. This is a stopgap until
# a better scheme for tagging core and extension enums is created.
self.enumdict = {}
for enums in self.reg.findall('enums'):
required = (enums.get('type') != None)
for enum in enums.findall('enum'):
enumInfo = EnumInfo(enum)
enumInfo.required = required
self.addElementInfo(enum, enumInfo, 'enum', self.enumdict)
#
# Create dictionary of registry commands from <command> tags
# and add 'name' attribute to each <command> tag (where missing)
# based on its <proto><name> element.
#
# There's usually only one <commands> block; more are OK.
# Required <command> attributes: 'name' or <proto><name> tag contents
self.cmddict = {}
for cmd in self.reg.findall('commands/command'):
# If the <command> doesn't already have a 'name' attribute, set
# it from contents of its <proto><name> tag.
if (cmd.get('name') == None):
cmd.attrib['name'] = cmd.find('proto/name').text
ci = CmdInfo(cmd)
self.addElementInfo(cmd, ci, 'command', self.cmddict)
#
# Create dictionaries of API and extension interfaces
# from toplevel <api> and <extension> tags.
#
self.apidict = {}
for feature in self.reg.findall('feature'):
featureInfo = FeatureInfo(feature)
self.addElementInfo(feature, featureInfo, 'feature', self.apidict)
self.extensions = self.reg.findall('extensions/extension')
self.extdict = {}
for feature in self.extensions:
featureInfo = FeatureInfo(feature)
self.addElementInfo(feature, featureInfo, 'extension',
self.extdict)
# Add additional enums defined only in <extension> tags
# to the corresponding core type.
# When seen here, the <enum> element, processed to contain the
# numeric enum value, is added to the corresponding <enums>
# element, as well as adding to the enum dictionary. It is
# *removed* from the <require> element it is introduced in.
# Not doing this will cause spurious genEnum()
# calls to be made in output generation, and it's easier
# to handle here than in genEnum().
#
# In lxml.etree, an Element can have only one parent, so the
# append() operation also removes the element. But in Python's
# ElementTree package, an Element can have multiple parents. So
# it must be explicitly removed from the <require> tag, leading
# to the nested loop traversal of <require>/<enum> elements
# below.
#
# This code also adds a 'extnumber' attribute containing the
# extension number, used for enumerant value calculation.
#
# For <enum> tags which are actually just constants, if there's
# no 'extends' tag but there is a 'value' or 'bitpos' tag, just
# add an EnumInfo record to the dictionary. That works because
# output generation of constants is purely dependency-based, and
# doesn't need to iterate through the XML tags.
#
# Something like this will need to be done for 'feature's up
# above, if we use the same mechanism for adding to the core
# API in 1.1.
#
for elem in feature.findall('require'):
for enum in elem.findall('enum'):
addEnumInfo = False
groupName = enum.get('extends')
if (groupName != None):
# self.gen.logMsg('diag', '*** Found extension enum',
# enum.get('name'))
# Add extension number attribute to the <enum> element
enum.attrib['extnumber'] = featureInfo.number
enum.attrib['extname'] = featureInfo.name
enum.attrib['supported'] = featureInfo.supported
# Look up the GroupInfo with matching groupName
if (groupName in self.groupdict.keys()):
# self.gen.logMsg('diag', '*** Matching group',
# groupName, 'found, adding element...')
gi = self.groupdict[groupName]
gi.elem.append(enum)
# Remove element from parent <require> tag
# This should be a no-op in lxml.etree
elem.remove(enum)
else:
self.gen.logMsg('warn', '*** NO matching group',
groupName, 'for enum',
enum.get('name'), 'found.')
addEnumInfo = True
elif (enum.get('value') or enum.get('bitpos')):
# self.gen.logMsg('diag', '*** Adding extension constant "enum"',
# enum.get('name'))
addEnumInfo = True
if (addEnumInfo):
enumInfo = EnumInfo(enum)
self.addElementInfo(enum, enumInfo, 'enum',
self.enumdict)
def dumpReg(self, maxlen=40, filehandle=sys.stdout):
"""Dump all the dictionaries constructed from the Registry object"""
write('***************************************', file=filehandle)
write(' ** Dumping Registry contents **', file=filehandle)
write('***************************************', file=filehandle)
write('// Types', file=filehandle)
for name in self.typedict:
tobj = self.typedict[name]
write(' Type',
name,
'->',
etree.tostring(tobj.elem)[0:maxlen],
file=filehandle)
write('// Groups', file=filehandle)
for name in self.groupdict:
gobj = self.groupdict[name]
write(' Group',
name,
'->',
etree.tostring(gobj.elem)[0:maxlen],
file=filehandle)
write('// Enums', file=filehandle)
for name in self.enumdict:
eobj = self.enumdict[name]
write(' Enum',
name,
'->',
etree.tostring(eobj.elem)[0:maxlen],
file=filehandle)
write('// Commands', file=filehandle)
for name in self.cmddict:
cobj = self.cmddict[name]
write(' Command',
name,
'->',
etree.tostring(cobj.elem)[0:maxlen],
file=filehandle)
write('// APIs', file=filehandle)
for key in self.apidict:
write(' API Version ',
key,
'->',
etree.tostring(self.apidict[key].elem)[0:maxlen],
file=filehandle)
write('// Extensions', file=filehandle)
for key in self.extdict:
write(' Extension',
key,
'->',
etree.tostring(self.extdict[key].elem)[0:maxlen],
file=filehandle)
# write('***************************************', file=filehandle)
# write(' ** Dumping XML ElementTree **', file=filehandle)
# write('***************************************', file=filehandle)
# write(etree.tostring(self.tree.getroot(),pretty_print=True), file=filehandle)
#
# typename - name of type
# required - boolean (to tag features as required or not)
def markTypeRequired(self, typename, required):
"""Require (along with its dependencies) or remove (but not its dependencies) a type"""
self.gen.logMsg('diag', '*** tagging type:', typename, '-> required =',
required)
# Get TypeInfo object for <type> tag corresponding to typename
type = self.lookupElementInfo(typename, self.typedict)
if (type != None):
if (required):
# Tag type dependencies in 'required' attributes as
# required. This DOES NOT un-tag dependencies in a <remove>
# tag. See comments in markRequired() below for the reason.
if ('requires' in type.elem.attrib):
depType = type.elem.get('requires')
self.gen.logMsg('diag', '*** Generating dependent type',
depType, 'for type', typename)
self.markTypeRequired(depType, required)
# Tag types used in defining this type (e.g. in nested
# <type> tags)
# Look for <type> in entire <command> tree,
# not just immediate children
for subtype in type.elem.findall('.//type'):
self.gen.logMsg(
'diag',
'*** markRequired: type requires dependent <type>',
subtype.text)
self.markTypeRequired(subtype.text, required)
# Tag enums used in defining this type, for example in
# <member><name>member</name>[<enum>MEMBER_SIZE</enum>]</member>
for subenum in type.elem.findall('.//enum'):
self.gen.logMsg(
'diag',
'*** markRequired: type requires dependent <enum>',
subenum.text)
self.markEnumRequired(subenum.text, required)
type.required = required
else:
self.gen.logMsg('warn', '*** type:', typename, 'IS NOT DEFINED')
#
# enumname - name of enum
# required - boolean (to tag features as required or not)
def markEnumRequired(self, enumname, required):
self.gen.logMsg('diag', '*** tagging enum:', enumname, '-> required =',
required)
enum = self.lookupElementInfo(enumname, self.enumdict)
if (enum != None):
enum.required = required
else:
self.gen.logMsg('warn', '*** enum:', enumname, 'IS NOT DEFINED')
#
# features - Element for <require> or <remove> tag
# required - boolean (to tag features as required or not)
def markRequired(self, features, required):
"""Require or remove features specified in the Element"""
self.gen.logMsg(
'diag',
'*** markRequired (features = <too long to print>, required =',
required, ')')
# Loop over types, enums, and commands in the tag
# @@ It would be possible to respect 'api' and 'profile' attributes
# in individual features, but that's not done yet.
for typeElem in features.findall('type'):
self.markTypeRequired(typeElem.get('name'), required)
for enumElem in features.findall('enum'):
self.markEnumRequired(enumElem.get('name'), required)
for cmdElem in features.findall('command'):
name = cmdElem.get('name')
self.gen.logMsg('diag', '*** tagging command:', name,
'-> required =', required)
cmd = self.lookupElementInfo(name, self.cmddict)
if (cmd != None):
cmd.required = required
# Tag all parameter types of this command as required.
# This DOES NOT remove types of commands in a <remove>
# tag, because many other commands may use the same type.
# We could be more clever and reference count types,
# instead of using a boolean.
if (required):
# Look for <type> in entire <command> tree,
# not just immediate children
for type in cmd.elem.findall('.//type'):
self.gen.logMsg(
'diag',
'*** markRequired: command implicitly requires dependent type',
type.text)
self.markTypeRequired(type.text, required)
else:
self.gen.logMsg('warn', '*** command:', name, 'IS NOT DEFINED')
#
# interface - Element for <version> or <extension>, containing
# <require> and <remove> tags
# api - string specifying API name being generated
# profile - string specifying API profile being generated
def requireAndRemoveFeatures(self, interface, api, profile):
"""Process <recquire> and <remove> tags for a <version> or <extension>"""
# <require> marks things that are required by this version/profile
for feature in interface.findall('require'):
if (matchAPIProfile(api, profile, feature)):
self.markRequired(feature, True)
# <remove> marks things that are removed by this version/profile
for feature in interface.findall('remove'):
if (matchAPIProfile(api, profile, feature)):
self.markRequired(feature, False)
def assignAdditionalValidity(self, interface, api, profile):
#
# Loop over all usage inside all <require> tags.
for feature in interface.findall('require'):
if (matchAPIProfile(api, profile, feature)):
for v in feature.findall('usage'):
if v.get('command'):
self.cmddict[v.get(
'command')].additionalValidity.append(
copy.deepcopy(v))
if v.get('struct'):
self.typedict[v.get(
'struct')].additionalValidity.append(
copy.deepcopy(v))
#
# Loop over all usage inside all <remove> tags.
for feature in interface.findall('remove'):
if (matchAPIProfile(api, profile, feature)):
for v in feature.findall('usage'):
if v.get('command'):
self.cmddict[v.get('command')].removedValidity.append(
copy.deepcopy(v))
if v.get('struct'):
self.typedict[v.get('struct')].removedValidity.append(
copy.deepcopy(v))
#
# generateFeature - generate a single type / enum group / enum / command,
# and all its dependencies as needed.
# fname - name of feature (<type>/<enum>/<command>)
# ftype - type of feature, 'type' | 'enum' | 'command'
# dictionary - of *Info objects - self.{type|enum|cmd}dict
def generateFeature(self, fname, ftype, dictionary):
f = self.lookupElementInfo(fname, dictionary)
if (f == None):
# No such feature. This is an error, but reported earlier
self.gen.logMsg('diag', '*** No entry found for feature', fname,
'returning!')
return
#
# If feature isn't required, or has already been declared, return
if (not f.required):
self.gen.logMsg('diag', '*** Skipping', ftype, fname,
'(not required)')
return
if (f.declared):
self.gen.logMsg('diag', '*** Skipping', ftype, fname,
'(already declared)')
return
# Always mark feature declared, as though actually emitted
f.declared = True
#
# Pull in dependent declaration(s) of the feature.
# For types, there may be one type in the 'required' attribute of
# the element, as well as many in imbedded <type> and <enum> tags
# within the element.
# For commands, there may be many in <type> tags within the element.
# For enums, no dependencies are allowed (though perhaps if you
# have a uint64 enum, it should require GLuint64).
genProc = None
if (ftype == 'type'):
genProc = self.gen.genType
if ('requires' in f.elem.attrib):
depname = f.elem.get('requires')
self.gen.logMsg('diag',
'*** Generating required dependent type',
depname)
self.generateFeature(depname, 'type', self.typedict)
for subtype in f.elem.findall('.//type'):
self.gen.logMsg('diag',
'*** Generating required dependent <type>',
subtype.text)
self.generateFeature(subtype.text, 'type', self.typedict)
for subtype in f.elem.findall('.//enum'):
self.gen.logMsg('diag',
'*** Generating required dependent <enum>',
subtype.text)
self.generateFeature(subtype.text, 'enum', self.enumdict)
# If the type is an enum group, look up the corresponding
# group in the group dictionary and generate that instead.
if (f.elem.get('category') == 'enum'):
self.gen.logMsg('diag', '*** Type', fname,
'is an enum group, so generate that instead')
group = self.lookupElementInfo(fname, self.groupdict)
if (group == None):
# Unless this is tested for, it's probably fatal to call below
genProc = None
self.logMsg('warn', '*** NO MATCHING ENUM GROUP FOUND!!!')
else:
genProc = self.gen.genGroup
f = group
elif (ftype == 'command'):
genProc = self.gen.genCmd
for type in f.elem.findall('.//type'):
depname = type.text
self.gen.logMsg('diag',
'*** Generating required parameter type',
depname)
self.generateFeature(depname, 'type', self.typedict)
elif (ftype == 'enum'):
genProc = self.gen.genEnum
# Actually generate the type only if emitting declarations
if self.emitFeatures:
self.gen.logMsg('diag', '*** Emitting', ftype, 'decl for', fname)
genProc(f, fname)
else:
self.gen.logMsg('diag', '*** Skipping', ftype, fname,
'(not emitting this feature)')
#
# generateRequiredInterface - generate all interfaces required
# by an API version or extension
# interface - Element for <version> or <extension>
def generateRequiredInterface(self, interface):
"""Generate required C interface for specified API version/extension"""
#
# Loop over all features inside all <require> tags.
for features in interface.findall('require'):
for t in features.findall('type'):
self.generateFeature(t.get('name'), 'type', self.typedict)
for e in features.findall('enum'):
self.generateFeature(e.get('name'), 'enum', self.enumdict)
for c in features.findall('command'):
self.generateFeature(c.get('name'), 'command', self.cmddict)
#
# apiGen(genOpts) - generate interface for specified versions
# genOpts - GeneratorOptions object with parameters used
# by the Generator object.
def apiGen(self, genOpts):
"""Generate interfaces for the specified API type and range of versions"""
#
self.gen.logMsg('diag', '*******************************************')
self.gen.logMsg('diag', ' Registry.apiGen file:', genOpts.filename,
'api:', genOpts.apiname, 'profile:', genOpts.profile)
self.gen.logMsg('diag', '*******************************************')
#
self.genOpts = genOpts
# Reset required/declared flags for all features
self.apiReset()
#
# Compile regexps used to select versions & extensions
regVersions = re.compile(self.genOpts.versions)
regEmitVersions = re.compile(self.genOpts.emitversions)
regAddExtensions = re.compile(self.genOpts.addExtensions)
regRemoveExtensions = re.compile(self.genOpts.removeExtensions)
#
# Get all matching API versions & add to list of FeatureInfo
features = []
apiMatch = False
for key in self.apidict:
fi = self.apidict[key]
api = fi.elem.get('api')
if (api == self.genOpts.apiname):
apiMatch = True
if (regVersions.match(fi.version)):
# Matches API & version #s being generated. Mark for
# emission and add to the features[] list .
# @@ Could use 'declared' instead of 'emit'?
fi.emit = (regEmitVersions.match(fi.version) != None)
features.append(fi)
if (not fi.emit):
self.gen.logMsg(
'diag', '*** NOT tagging feature api =', api,
'name =', fi.name, 'version =', fi.version,
'for emission (does not match emitversions pattern)'
)
else:
self.gen.logMsg('diag', '*** NOT including feature api =',
api, 'name =', fi.name, 'version =',
fi.version,
'(does not match requested versions)')
else:
self.gen.logMsg('diag', '*** NOT including feature api =', api,
'name =', fi.name,
'(does not match requested API)')
if (not apiMatch):
self.gen.logMsg('warn', '*** No matching API versions found!')
#
# Get all matching extensions, in order by their extension number,
# and add to the list of features.
# Start with extensions tagged with 'api' pattern matching the API
# being generated. Add extensions matching the pattern specified in
# regExtensions, then remove extensions matching the pattern
# specified in regRemoveExtensions
for (extName, ei) in sorted(self.extdict.items(),
key=lambda x: x[1].number):
extName = ei.name
include = False
#
# Include extension if defaultExtensions is not None and if the
# 'supported' attribute matches defaultExtensions. The regexp in
# 'supported' must exactly match defaultExtensions, so bracket
# it with ^(pat)$.
pat = '^(' + ei.elem.get('supported') + ')$'
if (self.genOpts.defaultExtensions
and re.match(pat, self.genOpts.defaultExtensions)):
self.gen.logMsg(
'diag', '*** Including extension', extName,
"(defaultExtensions matches the 'supported' attribute)")
include = True
#
# Include additional extensions if the extension name matches
# the regexp specified in the generator options. This allows
# forcing extensions into an interface even if they're not
# tagged appropriately in the registry.
if (regAddExtensions.match(extName) != None):
self.gen.logMsg(
'diag', '*** Including extension', extName,
'(matches explicitly requested extensions to add)')
include = True
# Remove extensions if the name matches the regexp specified
# in generator options. This allows forcing removal of
# extensions from an interface even if they're tagged that
# way in the registry.
if (regRemoveExtensions.match(extName) != None):
self.gen.logMsg(
'diag', '*** Removing extension', extName,
'(matches explicitly requested extensions to remove)')
include = False
#
# If the extension is to be included, add it to the
# extension features list.
if (include):
ei.emit = True
features.append(ei)
else:
self.gen.logMsg(
'diag', '*** NOT including extension', extName,
'(does not match api attribute or explicitly requested extensions)'
)
#
# Sort the extension features list, if a sort procedure is defined
if (self.genOpts.sortProcedure):
self.genOpts.sortProcedure(features)
#
# Pass 1: loop over requested API versions and extensions tagging
# types/commands/features as required (in an <require> block) or no
# longer required (in an <remove> block). It is possible to remove
# a feature in one version and restore it later by requiring it in
# a later version.
# If a profile other than 'None' is being generated, it must
# match the profile attribute (if any) of the <require> and
# <remove> tags.
self.gen.logMsg(
'diag',
'*** PASS 1: TAG FEATURES ********************************************'
)
for f in features:
self.gen.logMsg(
'diag',
'*** PASS 1: Tagging required and removed features for',
f.name)
self.requireAndRemoveFeatures(f.elem, self.genOpts.apiname,
self.genOpts.profile)
self.assignAdditionalValidity(f.elem, self.genOpts.apiname,
self.genOpts.profile)
#
# Pass 2: loop over specified API versions and extensions printing
# declarations for required things which haven't already been
# generated.
self.gen.logMsg(
'diag',
'*** PASS 2: GENERATE INTERFACES FOR FEATURES ************************'
)
self.gen.beginFile(self.genOpts)
for f in features:
self.gen.logMsg('diag', '*** PASS 2: Generating interface for',
f.name)
emit = self.emitFeatures = f.emit
if (not emit):
self.gen.logMsg('diag', '*** PASS 2: NOT declaring feature',
f.elem.get('name'),
'because it is not tagged for emission')
# Generate the interface (or just tag its elements as having been
# emitted, if they haven't been).
self.gen.beginFeature(f.elem, emit)
self.generateRequiredInterface(f.elem)
self.gen.endFeature()
self.gen.endFile()
#
# apiReset - use between apiGen() calls to reset internal state
#
def apiReset(self):
"""Reset type/enum/command dictionaries before generating another API"""
for type in self.typedict:
self.typedict[type].resetState()
for enum in self.enumdict:
self.enumdict[enum].resetState()
for cmd in self.cmddict:
self.cmddict[cmd].resetState()
for cmd in self.apidict:
self.apidict[cmd].resetState()
#
# validateGroups - check that group= attributes match actual groups
#
def validateGroups(self):
"""Validate group= attributes on <param> and <proto> tags"""
# Keep track of group names not in <group> tags
badGroup = {}
self.gen.logMsg('diag', '*** VALIDATING GROUP ATTRIBUTES ***')
for cmd in self.reg.findall('commands/command'):
proto = cmd.find('proto')
funcname = cmd.find('proto/name').text
if ('group' in proto.attrib.keys()):
group = proto.get('group')
# self.gen.logMsg('diag', '*** Command ', funcname, ' has return group ', group)
if (group not in self.groupdict.keys()):
# self.gen.logMsg('diag', '*** Command ', funcname, ' has UNKNOWN return group ', group)
if (group not in badGroup.keys()):
badGroup[group] = 1
else:
badGroup[group] = badGroup[group] + 1
for param in cmd.findall('param'):
pname = param.find('name')
if (pname != None):
pname = pname.text
else:
pname = type.get('name')
if ('group' in param.attrib.keys()):
group = param.get('group')
if (group not in self.groupdict.keys()):
# self.gen.logMsg('diag', '*** Command ', funcname, ' param ', pname, ' has UNKNOWN group ', group)
if (group not in badGroup.keys()):
badGroup[group] = 1
else:
badGroup[group] = badGroup[group] + 1
if (len(badGroup.keys()) > 0):
self.gen.logMsg('diag', '*** SUMMARY OF UNRECOGNIZED GROUPS ***')
for key in sorted(badGroup.keys()):
self.gen.logMsg('diag', ' ', key, ' occurred ',
badGroup[key], ' times')
def endFile(self):
OutputGenerator.endFile(self)
class Registry:
"""Represents an API registry loaded from XML"""
def __init__(self):
self.tree = None
self.typedict = {}
self.groupdict = {}
self.enumdict = {}
self.cmddict = {}
self.apidict = {}
self.extensions = []
self.extdict = {}
# A default output generator, so commands prior to apiGen can report
# errors via the generator object.
self.gen = OutputGenerator()
self.genOpts = None
self.emitFeatures = False
def loadElementTree(self, tree):
"""Load ElementTree into a Registry object and parse it"""
self.tree = tree
self.parseTree()
def loadFile(self, file):
"""Load an API registry XML file into a Registry object and parse it"""
self.tree = etree.parse(file)
self.parseTree()
def setGenerator(self, gen):
"""Specify output generator object. None restores the default generator"""
self.gen = gen
self.gen.setRegistry(self)
# addElementInfo - add information about an element to the
# corresponding dictionary
# elem - <type>/<enums>/<enum>/<command>/<feature>/<extension> Element
# info - corresponding {Type|Group|Enum|Cmd|Feature}Info object
# infoName - 'type' / 'group' / 'enum' / 'command' / 'feature' / 'extension'
# dictionary - self.{type|group|enum|cmd|api|ext}dict
# If the Element has an 'api' attribute, the dictionary key is the
# tuple (name,api). If not, the key is the name. 'name' is an
# attribute of the Element
def addElementInfo(self, elem, info, infoName, dictionary):
if ('api' in elem.attrib):
key = (elem.get('name'),elem.get('api'))
else:
key = elem.get('name')
if key in dictionary:
self.gen.logMsg('warn', '*** Attempt to redefine',
infoName, 'with key:', key)
else:
dictionary[key] = info
#
# lookupElementInfo - find a {Type|Enum|Cmd}Info object by name.
# If an object qualified by API name exists, use that.
# fname - name of type / enum / command
# dictionary - self.{type|enum|cmd}dict
def lookupElementInfo(self, fname, dictionary):
key = (fname, self.genOpts.apiname)
if (key in dictionary):
# self.gen.logMsg('diag', 'Found API-specific element for feature', fname)
return dictionary[key]
elif (fname in dictionary):
# self.gen.logMsg('diag', 'Found generic element for feature', fname)
return dictionary[fname]
else:
return None
def parseTree(self):
"""Parse the registry Element, once created"""
# This must be the Element for the root <registry>
self.reg = self.tree.getroot()
#
# Create dictionary of registry types from toplevel <types> tags
# and add 'name' attribute to each <type> tag (where missing)
# based on its <name> element.
#
# There's usually one <types> block; more are OK
# Required <type> attributes: 'name' or nested <name> tag contents
self.typedict = {}
for type in self.reg.findall('types/type'):
# If the <type> doesn't already have a 'name' attribute, set
# it from contents of its <name> tag.
if (type.get('name') == None):
type.attrib['name'] = type.find('name').text
self.addElementInfo(type, TypeInfo(type), 'type', self.typedict)
#
# Create dictionary of registry enum groups from <enums> tags.
#
# Required <enums> attributes: 'name'. If no name is given, one is
# generated, but that group can't be identified and turned into an
# enum type definition - it's just a container for <enum> tags.
self.groupdict = {}
for group in self.reg.findall('enums'):
self.addElementInfo(group, GroupInfo(group), 'group', self.groupdict)
#
# Create dictionary of registry enums from <enum> tags
#
# <enums> tags usually define different namespaces for the values
# defined in those tags, but the actual names all share the
# same dictionary.
# Required <enum> attributes: 'name', 'value'
# For containing <enums> which have type="enum" or type="bitmask",
# tag all contained <enum>s are required. This is a stopgap until
# a better scheme for tagging core and extension enums is created.
self.enumdict = {}
for enums in self.reg.findall('enums'):
required = (enums.get('type') != None)
for enum in enums.findall('enum'):
enumInfo = EnumInfo(enum)
enumInfo.required = required
self.addElementInfo(enum, enumInfo, 'enum', self.enumdict)
#
# Create dictionary of registry commands from <command> tags
# and add 'name' attribute to each <command> tag (where missing)
# based on its <proto><name> element.
#
# There's usually only one <commands> block; more are OK.
# Required <command> attributes: 'name' or <proto><name> tag contents
self.cmddict = {}
for cmd in self.reg.findall('commands/command'):
# If the <command> doesn't already have a 'name' attribute, set
# it from contents of its <proto><name> tag.
if (cmd.get('name') == None):
cmd.attrib['name'] = cmd.find('proto/name').text
ci = CmdInfo(cmd)
self.addElementInfo(cmd, ci, 'command', self.cmddict)
#
# Create dictionaries of API and extension interfaces
# from toplevel <api> and <extension> tags.
#
self.apidict = {}
for feature in self.reg.findall('feature'):
featureInfo = FeatureInfo(feature)
self.addElementInfo(feature, featureInfo, 'feature', self.apidict)
self.extensions = self.reg.findall('extensions/extension')
self.extdict = {}
for feature in self.extensions:
featureInfo = FeatureInfo(feature)
self.addElementInfo(feature, featureInfo, 'extension', self.extdict)
# Add additional enums defined only in <extension> tags
# to the corresponding core type.
# When seen here, the <enum> element, processed to contain the
# numeric enum value, is added to the corresponding <enums>
# element, as well as adding to the enum dictionary. It is
# *removed* from the <require> element it is introduced in.
# Not doing this will cause spurious genEnum()
# calls to be made in output generation, and it's easier
# to handle here than in genEnum().
#
# In lxml.etree, an Element can have only one parent, so the
# append() operation also removes the element. But in Python's
# ElementTree package, an Element can have multiple parents. So
# it must be explicitly removed from the <require> tag, leading
# to the nested loop traversal of <require>/<enum> elements
# below.
#
# This code also adds a 'extnumber' attribute containing the
# extension number, used for enumerant value calculation.
#
# For <enum> tags which are actually just constants, if there's
# no 'extends' tag but there is a 'value' or 'bitpos' tag, just
# add an EnumInfo record to the dictionary. That works because
# output generation of constants is purely dependency-based, and
# doesn't need to iterate through the XML tags.
#
# Something like this will need to be done for 'feature's up
# above, if we use the same mechanism for adding to the core
# API in 1.1.
#
for elem in feature.findall('require'):
for enum in elem.findall('enum'):
addEnumInfo = False
groupName = enum.get('extends')
if (groupName != None):
# self.gen.logMsg('diag', '*** Found extension enum',
# enum.get('name'))
# Add extension number attribute to the <enum> element
enum.attrib['extnumber'] = featureInfo.number
enum.attrib['extname'] = featureInfo.name
enum.attrib['supported'] = featureInfo.supported
# Look up the GroupInfo with matching groupName
if (groupName in self.groupdict.keys()):
# self.gen.logMsg('diag', '*** Matching group',
# groupName, 'found, adding element...')
gi = self.groupdict[groupName]
gi.elem.append(enum)
# Remove element from parent <require> tag
# This should be a no-op in lxml.etree
elem.remove(enum)
else:
self.gen.logMsg('warn', '*** NO matching group',
groupName, 'for enum', enum.get('name'), 'found.')
addEnumInfo = True
elif (enum.get('value') or enum.get('bitpos')):
# self.gen.logMsg('diag', '*** Adding extension constant "enum"',
# enum.get('name'))
addEnumInfo = True
if (addEnumInfo):
enumInfo = EnumInfo(enum)
self.addElementInfo(enum, enumInfo, 'enum', self.enumdict)
def dumpReg(self, maxlen = 40, filehandle = sys.stdout):
"""Dump all the dictionaries constructed from the Registry object"""
write('***************************************', file=filehandle)
write(' ** Dumping Registry contents **', file=filehandle)
write('***************************************', file=filehandle)
write('// Types', file=filehandle)
for name in self.typedict:
tobj = self.typedict[name]
write(' Type', name, '->', etree.tostring(tobj.elem)[0:maxlen], file=filehandle)
write('// Groups', file=filehandle)
for name in self.groupdict:
gobj = self.groupdict[name]
write(' Group', name, '->', etree.tostring(gobj.elem)[0:maxlen], file=filehandle)
write('// Enums', file=filehandle)
for name in self.enumdict:
eobj = self.enumdict[name]
write(' Enum', name, '->', etree.tostring(eobj.elem)[0:maxlen], file=filehandle)
write('// Commands', file=filehandle)
for name in self.cmddict:
cobj = self.cmddict[name]
write(' Command', name, '->', etree.tostring(cobj.elem)[0:maxlen], file=filehandle)
write('// APIs', file=filehandle)
for key in self.apidict:
write(' API Version ', key, '->',
etree.tostring(self.apidict[key].elem)[0:maxlen], file=filehandle)
write('// Extensions', file=filehandle)
for key in self.extdict:
write(' Extension', key, '->',
etree.tostring(self.extdict[key].elem)[0:maxlen], file=filehandle)
# write('***************************************', file=filehandle)
# write(' ** Dumping XML ElementTree **', file=filehandle)
# write('***************************************', file=filehandle)
# write(etree.tostring(self.tree.getroot(),pretty_print=True), file=filehandle)
#
# typename - name of type
# required - boolean (to tag features as required or not)
def markTypeRequired(self, typename, required):
"""Require (along with its dependencies) or remove (but not its dependencies) a type"""
self.gen.logMsg('diag', '*** tagging type:', typename, '-> required =', required)
# Get TypeInfo object for <type> tag corresponding to typename
type = self.lookupElementInfo(typename, self.typedict)
if (type != None):
if (required):
# Tag type dependencies in 'required' attributes as
# required. This DOES NOT un-tag dependencies in a <remove>
# tag. See comments in markRequired() below for the reason.
if ('requires' in type.elem.attrib):
depType = type.elem.get('requires')
self.gen.logMsg('diag', '*** Generating dependent type',
depType, 'for type', typename)
self.markTypeRequired(depType, required)
# Tag types used in defining this type (e.g. in nested
# <type> tags)
# Look for <type> in entire <command> tree,
# not just immediate children
for subtype in type.elem.findall('.//type'):
self.gen.logMsg('diag', '*** markRequired: type requires dependent <type>', subtype.text)
self.markTypeRequired(subtype.text, required)
# Tag enums used in defining this type, for example in
# <member><name>member</name>[<enum>MEMBER_SIZE</enum>]</member>
for subenum in type.elem.findall('.//enum'):
self.gen.logMsg('diag', '*** markRequired: type requires dependent <enum>', subenum.text)
self.markEnumRequired(subenum.text, required)
type.required = required
else:
self.gen.logMsg('warn', '*** type:', typename , 'IS NOT DEFINED')
#
# enumname - name of enum
# required - boolean (to tag features as required or not)
def markEnumRequired(self, enumname, required):
self.gen.logMsg('diag', '*** tagging enum:', enumname, '-> required =', required)
enum = self.lookupElementInfo(enumname, self.enumdict)
if (enum != None):
enum.required = required
else:
self.gen.logMsg('warn', '*** enum:', enumname , 'IS NOT DEFINED')
#
# features - Element for <require> or <remove> tag
# required - boolean (to tag features as required or not)
def markRequired(self, features, required):
"""Require or remove features specified in the Element"""
self.gen.logMsg('diag', '*** markRequired (features = <too long to print>, required =', required, ')')
# Loop over types, enums, and commands in the tag
# @@ It would be possible to respect 'api' and 'profile' attributes
# in individual features, but that's not done yet.
for typeElem in features.findall('type'):
self.markTypeRequired(typeElem.get('name'), required)
for enumElem in features.findall('enum'):
self.markEnumRequired(enumElem.get('name'), required)
for cmdElem in features.findall('command'):
name = cmdElem.get('name')
self.gen.logMsg('diag', '*** tagging command:', name, '-> required =', required)
cmd = self.lookupElementInfo(name, self.cmddict)
if (cmd != None):
cmd.required = required
# Tag all parameter types of this command as required.
# This DOES NOT remove types of commands in a <remove>
# tag, because many other commands may use the same type.
# We could be more clever and reference count types,
# instead of using a boolean.
if (required):
# Look for <type> in entire <command> tree,
# not just immediate children
for type in cmd.elem.findall('.//type'):
self.gen.logMsg('diag', '*** markRequired: command implicitly requires dependent type', type.text)
self.markTypeRequired(type.text, required)
else:
self.gen.logMsg('warn', '*** command:', name, 'IS NOT DEFINED')
#
# interface - Element for <version> or <extension>, containing
# <require> and <remove> tags
# api - string specifying API name being generated
# profile - string specifying API profile being generated
def requireAndRemoveFeatures(self, interface, api, profile):
"""Process <recquire> and <remove> tags for a <version> or <extension>"""
# <require> marks things that are required by this version/profile
for feature in interface.findall('require'):
if (matchAPIProfile(api, profile, feature)):
self.markRequired(feature,True)
# <remove> marks things that are removed by this version/profile
for feature in interface.findall('remove'):
if (matchAPIProfile(api, profile, feature)):
self.markRequired(feature,False)
def assignAdditionalValidity(self, interface, api, profile):
#
# Loop over all usage inside all <require> tags.
for feature in interface.findall('require'):
if (matchAPIProfile(api, profile, feature)):
for v in feature.findall('usage'):
if v.get('command'):
self.cmddict[v.get('command')].additionalValidity.append(copy.deepcopy(v))
if v.get('struct'):
self.typedict[v.get('struct')].additionalValidity.append(copy.deepcopy(v))
#
# Loop over all usage inside all <remove> tags.
for feature in interface.findall('remove'):
if (matchAPIProfile(api, profile, feature)):
for v in feature.findall('usage'):
if v.get('command'):
self.cmddict[v.get('command')].removedValidity.append(copy.deepcopy(v))
if v.get('struct'):
self.typedict[v.get('struct')].removedValidity.append(copy.deepcopy(v))
#
# generateFeature - generate a single type / enum group / enum / command,
# and all its dependencies as needed.
# fname - name of feature (<type>/<enum>/<command>)
# ftype - type of feature, 'type' | 'enum' | 'command'
# dictionary - of *Info objects - self.{type|enum|cmd}dict
def generateFeature(self, fname, ftype, dictionary):
f = self.lookupElementInfo(fname, dictionary)
if (f == None):
# No such feature. This is an error, but reported earlier
self.gen.logMsg('diag', '*** No entry found for feature', fname,
'returning!')
return
#
# If feature isn't required, or has already been declared, return
if (not f.required):
self.gen.logMsg('diag', '*** Skipping', ftype, fname, '(not required)')
return
if (f.declared):
self.gen.logMsg('diag', '*** Skipping', ftype, fname, '(already declared)')
return
# Always mark feature declared, as though actually emitted
f.declared = True
#
# Pull in dependent declaration(s) of the feature.
# For types, there may be one type in the 'required' attribute of
# the element, as well as many in imbedded <type> and <enum> tags
# within the element.
# For commands, there may be many in <type> tags within the element.
# For enums, no dependencies are allowed (though perhaps if you
# have a uint64 enum, it should require GLuint64).
genProc = None
if (ftype == 'type'):
genProc = self.gen.genType
if ('requires' in f.elem.attrib):
depname = f.elem.get('requires')
self.gen.logMsg('diag', '*** Generating required dependent type',
depname)
self.generateFeature(depname, 'type', self.typedict)
for subtype in f.elem.findall('.//type'):
self.gen.logMsg('diag', '*** Generating required dependent <type>',
subtype.text)
self.generateFeature(subtype.text, 'type', self.typedict)
for subtype in f.elem.findall('.//enum'):
self.gen.logMsg('diag', '*** Generating required dependent <enum>',
subtype.text)
self.generateFeature(subtype.text, 'enum', self.enumdict)
# If the type is an enum group, look up the corresponding
# group in the group dictionary and generate that instead.
if (f.elem.get('category') == 'enum'):
self.gen.logMsg('diag', '*** Type', fname, 'is an enum group, so generate that instead')
group = self.lookupElementInfo(fname, self.groupdict)
if (group == None):
# Unless this is tested for, it's probably fatal to call below
genProc = None
self.logMsg('warn', '*** NO MATCHING ENUM GROUP FOUND!!!')
else:
genProc = self.gen.genGroup
f = group
elif (ftype == 'command'):
genProc = self.gen.genCmd
for type in f.elem.findall('.//type'):
depname = type.text
self.gen.logMsg('diag', '*** Generating required parameter type',
depname)
self.generateFeature(depname, 'type', self.typedict)
elif (ftype == 'enum'):
genProc = self.gen.genEnum
# Actually generate the type only if emitting declarations
if self.emitFeatures:
self.gen.logMsg('diag', '*** Emitting', ftype, 'decl for', fname)
genProc(f, fname)
else:
self.gen.logMsg('diag', '*** Skipping', ftype, fname,
'(not emitting this feature)')
#
# generateRequiredInterface - generate all interfaces required
# by an API version or extension
# interface - Element for <version> or <extension>
def generateRequiredInterface(self, interface):
"""Generate required C interface for specified API version/extension"""
#
# Loop over all features inside all <require> tags.
for features in interface.findall('require'):
for t in features.findall('type'):
self.generateFeature(t.get('name'), 'type', self.typedict)
for e in features.findall('enum'):
self.generateFeature(e.get('name'), 'enum', self.enumdict)
for c in features.findall('command'):
self.generateFeature(c.get('name'), 'command', self.cmddict)
#
# apiGen(genOpts) - generate interface for specified versions
# genOpts - GeneratorOptions object with parameters used
# by the Generator object.
def apiGen(self, genOpts):
"""Generate interfaces for the specified API type and range of versions"""
#
self.gen.logMsg('diag', '*******************************************')
self.gen.logMsg('diag', ' Registry.apiGen file:', genOpts.filename,
'api:', genOpts.apiname,
'profile:', genOpts.profile)
self.gen.logMsg('diag', '*******************************************')
#
self.genOpts = genOpts
# Reset required/declared flags for all features
self.apiReset()
#
# Compile regexps used to select versions & extensions
regVersions = re.compile(self.genOpts.versions)
regEmitVersions = re.compile(self.genOpts.emitversions)
regAddExtensions = re.compile(self.genOpts.addExtensions)
regRemoveExtensions = re.compile(self.genOpts.removeExtensions)
#
# Get all matching API versions & add to list of FeatureInfo
features = []
apiMatch = False
for key in self.apidict:
fi = self.apidict[key]
api = fi.elem.get('api')
if (api == self.genOpts.apiname):
apiMatch = True
if (regVersions.match(fi.version)):
# Matches API & version #s being generated. Mark for
# emission and add to the features[] list .
# @@ Could use 'declared' instead of 'emit'?
fi.emit = (regEmitVersions.match(fi.version) != None)
features.append(fi)
if (not fi.emit):
self.gen.logMsg('diag', '*** NOT tagging feature api =', api,
'name =', fi.name, 'version =', fi.version,
'for emission (does not match emitversions pattern)')
else:
self.gen.logMsg('diag', '*** NOT including feature api =', api,
'name =', fi.name, 'version =', fi.version,
'(does not match requested versions)')
else:
self.gen.logMsg('diag', '*** NOT including feature api =', api,
'name =', fi.name,
'(does not match requested API)')
if (not apiMatch):
self.gen.logMsg('warn', '*** No matching API versions found!')
#
# Get all matching extensions, in order by their extension number,
# and add to the list of features.
# Start with extensions tagged with 'api' pattern matching the API
# being generated. Add extensions matching the pattern specified in
# regExtensions, then remove extensions matching the pattern
# specified in regRemoveExtensions
for (extName,ei) in sorted(self.extdict.items(),key = lambda x : x[1].number):
extName = ei.name
include = False
#
# Include extension if defaultExtensions is not None and if the
# 'supported' attribute matches defaultExtensions. The regexp in
# 'supported' must exactly match defaultExtensions, so bracket
# it with ^(pat)$.
pat = '^(' + ei.elem.get('supported') + ')$'
if (self.genOpts.defaultExtensions and
re.match(pat, self.genOpts.defaultExtensions)):
self.gen.logMsg('diag', '*** Including extension',
extName, "(defaultExtensions matches the 'supported' attribute)")
include = True
#
# Include additional extensions if the extension name matches
# the regexp specified in the generator options. This allows
# forcing extensions into an interface even if they're not
# tagged appropriately in the registry.
if (regAddExtensions.match(extName) != None):
self.gen.logMsg('diag', '*** Including extension',
extName, '(matches explicitly requested extensions to add)')
include = True
# Remove extensions if the name matches the regexp specified
# in generator options. This allows forcing removal of
# extensions from an interface even if they're tagged that
# way in the registry.
if (regRemoveExtensions.match(extName) != None):
self.gen.logMsg('diag', '*** Removing extension',
extName, '(matches explicitly requested extensions to remove)')
include = False
#
# If the extension is to be included, add it to the
# extension features list.
if (include):
ei.emit = True
features.append(ei)
else:
self.gen.logMsg('diag', '*** NOT including extension',
extName, '(does not match api attribute or explicitly requested extensions)')
#
# Sort the extension features list, if a sort procedure is defined
if (self.genOpts.sortProcedure):
self.genOpts.sortProcedure(features)
#
# Pass 1: loop over requested API versions and extensions tagging
# types/commands/features as required (in an <require> block) or no
# longer required (in an <remove> block). It is possible to remove
# a feature in one version and restore it later by requiring it in
# a later version.
# If a profile other than 'None' is being generated, it must
# match the profile attribute (if any) of the <require> and
# <remove> tags.
self.gen.logMsg('diag', '*** PASS 1: TAG FEATURES ********************************************')
for f in features:
self.gen.logMsg('diag', '*** PASS 1: Tagging required and removed features for',
f.name)
self.requireAndRemoveFeatures(f.elem, self.genOpts.apiname, self.genOpts.profile)
self.assignAdditionalValidity(f.elem, self.genOpts.apiname, self.genOpts.profile)
#
# Pass 2: loop over specified API versions and extensions printing
# declarations for required things which haven't already been
# generated.
self.gen.logMsg('diag', '*** PASS 2: GENERATE INTERFACES FOR FEATURES ************************')
self.gen.beginFile(self.genOpts)
for f in features:
self.gen.logMsg('diag', '*** PASS 2: Generating interface for',
f.name)
emit = self.emitFeatures = f.emit
if (not emit):
self.gen.logMsg('diag', '*** PASS 2: NOT declaring feature',
f.elem.get('name'), 'because it is not tagged for emission')
# Generate the interface (or just tag its elements as having been
# emitted, if they haven't been).
self.gen.beginFeature(f.elem, emit)
self.generateRequiredInterface(f.elem)
self.gen.endFeature()
self.gen.endFile()
#
# apiReset - use between apiGen() calls to reset internal state
#
def apiReset(self):
"""Reset type/enum/command dictionaries before generating another API"""
for type in self.typedict:
self.typedict[type].resetState()
for enum in self.enumdict:
self.enumdict[enum].resetState()
for cmd in self.cmddict:
self.cmddict[cmd].resetState()
for cmd in self.apidict:
self.apidict[cmd].resetState()
#
# validateGroups - check that group= attributes match actual groups
#
def validateGroups(self):
"""Validate group= attributes on <param> and <proto> tags"""
# Keep track of group names not in <group> tags
badGroup = {}
self.gen.logMsg('diag', '*** VALIDATING GROUP ATTRIBUTES ***')
for cmd in self.reg.findall('commands/command'):
proto = cmd.find('proto')
funcname = cmd.find('proto/name').text
if ('group' in proto.attrib.keys()):
group = proto.get('group')
# self.gen.logMsg('diag', '*** Command ', funcname, ' has return group ', group)
if (group not in self.groupdict.keys()):
# self.gen.logMsg('diag', '*** Command ', funcname, ' has UNKNOWN return group ', group)
if (group not in badGroup.keys()):
badGroup[group] = 1
else:
badGroup[group] = badGroup[group] + 1
for param in cmd.findall('param'):
pname = param.find('name')
if (pname != None):
pname = pname.text
else:
pname = type.get('name')
if ('group' in param.attrib.keys()):
group = param.get('group')
if (group not in self.groupdict.keys()):
# self.gen.logMsg('diag', '*** Command ', funcname, ' param ', pname, ' has UNKNOWN group ', group)
if (group not in badGroup.keys()):
badGroup[group] = 1
else:
badGroup[group] = badGroup[group] + 1
if (len(badGroup.keys()) > 0):
self.gen.logMsg('diag', '*** SUMMARY OF UNRECOGNIZED GROUPS ***')
for key in sorted(badGroup.keys()):
self.gen.logMsg('diag', ' ', key, ' occurred ', badGroup[key], ' times')
def endFile(self):
self.extensions.sort()
# Generate metadoc extension files, in refpage and non-refpage form
for ext in self.extensions:
ext.makeMetafile(self.extensions, isRefpage=False)
if self.conventions.write_refpage_include:
ext.makeMetafile(self.extensions, isRefpage=True)
# Generate list of promoted extensions
promotedExtensions = {}
for ext in self.extensions:
if ext.deprecationType == 'promotion' and ext.supercedingAPIVersion:
promotedExtensions.setdefault(ext.supercedingAPIVersion,
[]).append(ext)
for coreVersion, extensions in promotedExtensions.items():
promoted_extensions_fp = self.newFile(self.directory +
'/promoted_extensions_' +
coreVersion +
self.file_suffix)
for ext in extensions:
indent = ''
write(' * {blank}\n+\n' +
ext.conditionalLinkExt(ext.name, indent),
file=promoted_extensions_fp)
promoted_extensions_fp.close()
# Re-sort to match earlier behavior
# TODO: Remove this extra sort when re-arranging section order OK.
def makeSortKey(ext):
name = ext.name.lower()
prefixes = self.conventions.extension_index_prefixes
for i, prefix in enumerate(prefixes):
if ext.name.startswith(prefix):
return (i, name)
return (len(prefixes), name)
self.extensions.sort(key=makeSortKey)
# Generate include directives for the extensions appendix, grouping
# extensions by status (current, deprecated, provisional, etc.)
with self.newFile(self.directory + '/current_extensions_appendix' + self.file_suffix) as current_extensions_appendix_fp, \
self.newFile(self.directory + '/deprecated_extensions_appendix' + self.file_suffix) as deprecated_extensions_appendix_fp, \
self.newFile(self.directory + '/current_extension_appendices' + self.file_suffix) as current_extension_appendices_fp, \
self.newFile(self.directory + '/current_extension_appendices_toc' + self.file_suffix) as current_extension_appendices_toc_fp, \
self.newFile(self.directory + '/deprecated_extension_appendices' + self.file_suffix) as deprecated_extension_appendices_fp, \
self.newFile(self.directory + '/deprecated_extension_appendices_toc' + self.file_suffix) as deprecated_extension_appendices_toc_fp, \
self.newFile(self.directory + '/deprecated_extensions_guard_macro' + self.file_suffix) as deprecated_extensions_guard_macro_fp, \
self.newFile(self.directory + '/provisional_extensions_appendix' + self.file_suffix) as provisional_extensions_appendix_fp, \
self.newFile(self.directory + '/provisional_extension_appendices' + self.file_suffix) as provisional_extension_appendices_fp, \
self.newFile(self.directory + '/provisional_extension_appendices_toc' + self.file_suffix) as provisional_extension_appendices_toc_fp, \
self.newFile(self.directory + '/provisional_extensions_guard_macro' + self.file_suffix) as provisional_extensions_guard_macro_fp:
write('include::deprecated_extensions_guard_macro' +
self.file_suffix + '[]',
file=current_extensions_appendix_fp)
write('', file=current_extensions_appendix_fp)
write('ifndef::HAS_DEPRECATED_EXTENSIONS[]',
file=current_extensions_appendix_fp)
write('[[extension-appendices-list]]',
file=current_extensions_appendix_fp)
write('== List of Extensions', file=current_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]',
file=current_extensions_appendix_fp)
write('ifdef::HAS_DEPRECATED_EXTENSIONS[]',
file=current_extensions_appendix_fp)
write('[[extension-appendices-list]]',
file=current_extensions_appendix_fp)
write('== List of Current Extensions',
file=current_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]',
file=current_extensions_appendix_fp)
write('', file=current_extensions_appendix_fp)
write('include::current_extension_appendices_toc' +
self.file_suffix + '[]',
file=current_extensions_appendix_fp)
write('<<<', file=current_extensions_appendix_fp)
write('include::current_extension_appendices' + self.file_suffix +
'[]',
file=current_extensions_appendix_fp)
write('include::deprecated_extensions_guard_macro' +
self.file_suffix + '[]',
file=deprecated_extensions_appendix_fp)
write('', file=deprecated_extensions_appendix_fp)
write('ifdef::HAS_DEPRECATED_EXTENSIONS[]',
file=deprecated_extensions_appendix_fp)
write('[[deprecated-extension-appendices-list]]',
file=deprecated_extensions_appendix_fp)
write('== List of Deprecated Extensions',
file=deprecated_extensions_appendix_fp)
write('include::deprecated_extension_appendices_toc' +
self.file_suffix + '[]',
file=deprecated_extensions_appendix_fp)
write('<<<', file=deprecated_extensions_appendix_fp)
write('include::deprecated_extension_appendices' +
self.file_suffix + '[]',
file=deprecated_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]',
file=deprecated_extensions_appendix_fp)
# add include guard to allow multiple includes
write('ifndef::DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]',
file=deprecated_extensions_guard_macro_fp)
write(':DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD:\n',
file=deprecated_extensions_guard_macro_fp)
write('ifndef::PROVISIONAL_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]',
file=provisional_extensions_guard_macro_fp)
write(':PROVISIONAL_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD:\n',
file=provisional_extensions_guard_macro_fp)
write('include::provisional_extensions_guard_macro' +
self.file_suffix + '[]',
file=provisional_extensions_appendix_fp)
write('', file=provisional_extensions_appendix_fp)
write('ifdef::HAS_PROVISIONAL_EXTENSIONS[]',
file=provisional_extensions_appendix_fp)
write('[[provisional-extension-appendices-list]]',
file=provisional_extensions_appendix_fp)
write('== List of Provisional Extensions',
file=provisional_extensions_appendix_fp)
write('include::provisional_extension_appendices_toc' +
self.file_suffix + '[]',
file=provisional_extensions_appendix_fp)
write('<<<', file=provisional_extensions_appendix_fp)
write('include::provisional_extension_appendices' +
self.file_suffix + '[]',
file=provisional_extensions_appendix_fp)
write('endif::HAS_PROVISIONAL_EXTENSIONS[]',
file=provisional_extensions_appendix_fp)
for ext in self.extensions:
include = self.makeExtensionInclude(ext)
link = ' * ' + self.conventions.formatExtension(ext.name)
if ext.provisional == 'true':
write(self.conditionalExt(ext.name, include),
file=provisional_extension_appendices_fp)
write(self.conditionalExt(ext.name, link),
file=provisional_extension_appendices_toc_fp)
write(self.conditionalExt(ext.name,
':HAS_PROVISIONAL_EXTENSIONS:'),
file=provisional_extensions_guard_macro_fp)
elif ext.deprecationType is None:
write(self.conditionalExt(ext.name, include),
file=current_extension_appendices_fp)
write(self.conditionalExt(ext.name, link),
file=current_extension_appendices_toc_fp)
else:
condition = ext.supercedingAPIVersion if ext.supercedingAPIVersion else ext.supercedingExtension # potentially None too
write(self.conditionalExt(ext.name, include, 'ifndef',
condition),
file=current_extension_appendices_fp)
write(self.conditionalExt(ext.name, link, 'ifndef',
condition),
file=current_extension_appendices_toc_fp)
write(self.conditionalExt(ext.name, include, 'ifdef',
condition),
file=deprecated_extension_appendices_fp)
write(self.conditionalExt(ext.name, link, 'ifdef',
condition),
file=deprecated_extension_appendices_toc_fp)
write(self.conditionalExt(ext.name,
':HAS_DEPRECATED_EXTENSIONS:',
'ifdef', condition),
file=deprecated_extensions_guard_macro_fp)
write('endif::DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]',
file=deprecated_extensions_guard_macro_fp)
OutputGenerator.endFile(self)
def endFile(self):
# Generate metadoc feature files, in refpage and non-refpage form
for feature in self.features:
self.makeInterfaceFile(feature)
OutputGenerator.endFile(self)
def endFile(self):
self.extensions.sort()
for ext in self.extensions:
ext.makeMetafile(self.extensions)
promotedExtensions = {}
for ext in self.extensions:
if ext.deprecationType == 'promotion' and ext.supercedingAPIVersion:
promotedExtensions.setdefault(ext.supercedingAPIVersion,
[]).append(ext)
for coreVersion, extensions in promotedExtensions.items():
promoted_extensions_fp = self.newFile(self.directory +
'/promoted_extensions_' +
coreVersion +
self.file_suffix)
for ext in extensions:
indent = ''
write(' * {blank}\n+\n' +
ext.conditionalLinkExt(ext.name, indent),
file=promoted_extensions_fp)
promoted_extensions_fp.close()
current_extensions_appendix_fp = self.newFile(
self.directory + '/current_extensions_appendix' + self.file_suffix)
deprecated_extensions_appendix_fp = self.newFile(
self.directory + '/deprecated_extensions_appendix' +
self.file_suffix)
current_extension_appendices_fp = self.newFile(
self.directory + '/current_extension_appendices' +
self.file_suffix)
current_extension_appendices_toc_fp = self.newFile(
self.directory + '/current_extension_appendices_toc' +
self.file_suffix)
deprecated_extension_appendices_fp = self.newFile(
self.directory + '/deprecated_extension_appendices' +
self.file_suffix)
deprecated_extension_appendices_toc_fp = self.newFile(
self.directory + '/deprecated_extension_appendices_toc' +
self.file_suffix)
deprecated_extensions_guard_macro_fp = self.newFile(
self.directory + '/deprecated_extensions_guard_macro' +
self.file_suffix)
write('include::deprecated_extensions_guard_macro' + self.file_suffix +
'[]',
file=current_extensions_appendix_fp)
write('', file=current_extensions_appendix_fp)
write('ifndef::HAS_DEPRECATED_EXTENSIONS[]',
file=current_extensions_appendix_fp)
write('[[extension-appendices-list]]',
file=current_extensions_appendix_fp)
write('== List of Extensions', file=current_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]',
file=current_extensions_appendix_fp)
write('ifdef::HAS_DEPRECATED_EXTENSIONS[]',
file=current_extensions_appendix_fp)
write('[[extension-appendices-list]]',
file=current_extensions_appendix_fp)
write('== List of Current Extensions',
file=current_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]',
file=current_extensions_appendix_fp)
write('', file=current_extensions_appendix_fp)
write('include::current_extension_appendices_toc' + self.file_suffix +
'[]',
file=current_extensions_appendix_fp)
write('<<<', file=current_extensions_appendix_fp)
write('include::current_extension_appendices' + self.file_suffix +
'[]',
file=current_extensions_appendix_fp)
write('include::deprecated_extensions_guard_macro' + self.file_suffix +
'[]',
file=deprecated_extensions_appendix_fp)
write('', file=deprecated_extensions_appendix_fp)
write('ifdef::HAS_DEPRECATED_EXTENSIONS[]',
file=deprecated_extensions_appendix_fp)
write('[[deprecated-extension-appendices-list]]',
file=deprecated_extensions_appendix_fp)
write('== List of Deprecated Extensions',
file=deprecated_extensions_appendix_fp)
write('include::deprecated_extension_appendices_toc' +
self.file_suffix + '[]',
file=deprecated_extensions_appendix_fp)
write('<<<', file=deprecated_extensions_appendix_fp)
write('include::deprecated_extension_appendices' + self.file_suffix +
'[]',
file=deprecated_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]',
file=deprecated_extensions_appendix_fp)
# add include guard to allow multiple includes
write('ifndef::DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]',
file=deprecated_extensions_guard_macro_fp)
write(':DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD:\n',
file=deprecated_extensions_guard_macro_fp)
self.extensions.sort(key=lambda ext: ext.name.lower())
EXT_prefix = self.genOpts.conventions.EXT_prefix
KHR_prefix = self.genOpts.conventions.KHR_prefix
# Output all KHR extensions
for ext in self.extensions:
if ext.name.startswith(KHR_prefix):
condition = ext.supercedingAPIVersion if ext.supercedingAPIVersion else ext.supercedingExtension
self.outputExtensionInclude(
ext.name, 'KHR', ext.deprecationType, condition,
current_extension_appendices_fp,
current_extension_appendices_toc_fp,
deprecated_extension_appendices_fp,
deprecated_extension_appendices_toc_fp,
deprecated_extensions_guard_macro_fp)
# Next, output all EXT extensions
for ext in self.extensions:
if ext.name.startswith(EXT_prefix):
condition = ext.supercedingAPIVersion if ext.supercedingAPIVersion else ext.supercedingExtension
self.outputExtensionInclude(
ext.name, 'EXT', ext.deprecationType, condition,
current_extension_appendices_fp,
current_extension_appendices_toc_fp,
deprecated_extension_appendices_fp,
deprecated_extension_appendices_toc_fp,
deprecated_extensions_guard_macro_fp)
api_prefix = self.genOpts.conventions.api_prefix
# Finally, output the rest
for ext in self.extensions:
# Skip KHR and EXT
if ext.name.startswith(KHR_prefix) or ext.name.startswith(
EXT_prefix):
continue
found_vendor_tag = False
vendor_tag = ''
for cur_vendor_tag in self.vendor_tags:
vendor_tag_prefix = api_prefix + cur_vendor_tag + '_'
if ext.name.startswith(vendor_tag_prefix):
found_vendor_tag = True
vendor_tag = cur_vendor_tag
break
if not found_vendor_tag:
self.logMsg(
'warn', 'Unknown vendor tag for extension ' + ext.name +
', dropping from list.')
condition = ext.supercedingAPIVersion if ext.supercedingAPIVersion else ext.supercedingExtension
self.outputExtensionInclude(
ext.name, vendor_tag, ext.deprecationType, condition,
current_extension_appendices_fp,
current_extension_appendices_toc_fp,
deprecated_extension_appendices_fp,
deprecated_extension_appendices_toc_fp,
deprecated_extensions_guard_macro_fp)
current_extensions_appendix_fp.close()
deprecated_extensions_appendix_fp.close()
current_extension_appendices_fp.close()
current_extension_appendices_toc_fp.close()
deprecated_extension_appendices_fp.close()
deprecated_extension_appendices_toc_fp.close()
write('endif::DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]',
file=deprecated_extensions_guard_macro_fp)
deprecated_extensions_guard_macro_fp.close()
OutputGenerator.endFile(self)
def endFile(self):
captable = []
exttable = []
# How to "indent" a pseudo-column for better use of space.
# {captableindent} is defined in appendices/spirvenv.txt
indent = '{captableindent}'
for elem in self.spirv:
conditions = self.getConditions(elem)
# Combine all conditions for enables and surround the row with
# them
if len(conditions) > 0:
condition_string = ','.join(conditions)
prefix = ['ifdef::{}[]'.format(condition_string)]
suffix = ['endif::{}[]'.format(condition_string)]
else:
prefix = []
suffix = []
body = []
# Generate an anchor for each capability
if elem.tag == 'spirvcapability':
body.append('[[spirvenv-capabilities-table-{}]]'.format(
elem.get('name')))
# <spirvextension> entries don't get anchors
# First "cell" in a table row, and a break for the other "cells"
body.append('| code:{} +'.format(elem.get('name')))
# Iterate over each enable emitting a formatting tag for it
# Protect the term if there is a version or extension
# requirement, and if there are multiple enables (otherwise,
# the ifdef protecting the entire row will suffice).
enables = [e for e in elem.findall('enable')]
remaining = len(enables)
for subelem in enables:
remaining -= 1
if subelem.get('version'):
version = subelem.get('version')
# Convert API enum VK_API_VERSION_m_n to conditional
# used for spec builds (VK_VERSION_m_n)
enable = version.replace('API_', '')
# Convert API enum to anchor for version appendices (versions-m.n)
link = 'versions-' + version[-3:].replace('_', '.')
altlink = version
elif subelem.get('extension'):
extension = subelem.get('extension')
enable = extension
link = extension
altlink = None
elif subelem.get('struct'):
struct = subelem.get('struct')
feature = subelem.get('feature')
requires = subelem.get('requires')
alias = subelem.get('alias')
link_name = feature
# For cases, like bufferDeviceAddressEXT where need manual help
if alias:
link_name = alias
enable = requires
link = 'features-' + link_name
altlink = 'sname:{}::pname:{}'.format(struct, feature)
else:
property = subelem.get('property')
member = subelem.get('member')
requires = subelem.get('requires')
value = subelem.get('value')
enable = requires
# Properties should have a "feature" prefix
link = 'limits-' + member
# Display the property value by itself if it is not a boolean (matches original table)
# DenormPreserve is an example where it makes sense to just show the
# member value as it is just a boolean and the name implies "true"
# GroupNonUniformVote is an example where the whole name is too long
# better to just display the value
if value == "VK_TRUE":
altlink = 'sname:{}::pname:{}'.format(property, member)
else:
altlink = '{}'.format(value)
# If there are no more enables, don't continue the last line
if remaining > 0:
continuation = ' +'
else:
continuation = ''
# condition_string != enable is a small optimization
if enable is not None and condition_string != enable:
body.append('ifdef::{}[]'.format(enable))
if altlink is not None:
## Want to add ' +' to all but last line
body.append('{} <<{},{}>>{}'.format(
indent, link, altlink, continuation))
else:
body.append('{} <<{}>>{}'.format(indent, link,
continuation))
if enable is not None and condition_string != enable:
body.append('endif::{}[]'.format(enable))
if elem.tag == 'spirvcapability':
captable += prefix + body + suffix
else:
exttable += prefix + body + suffix
# Generate the asciidoc include files
self.writeBlock('captable.txt', captable)
self.writeBlock('exttable.txt', exttable)
# Finish processing in superclass
OutputGenerator.endFile(self)
def endFile(self):
self.extensions.sort()
for ext in self.extensions:
ext.makeMetafile(self.extensions)
promotedExtensions = {}
for ext in self.extensions:
if ext.deprecationType == 'promotion' and ext.supercedingAPIVersion:
promotedExtensions.setdefault(ext.supercedingAPIVersion, []).append(ext)
for coreVersion, extensions in promotedExtensions.items():
promoted_extensions_fp = self.newFile(self.directory + '/promoted_extensions_' + coreVersion + self.file_suffix)
for ext in extensions:
indent = ''
write(' * {blank}\n+\n' + ext.conditionalLinkExt(ext.name, indent), file=promoted_extensions_fp)
promoted_extensions_fp.close()
current_extensions_appendix_fp = self.newFile(self.directory + '/current_extensions_appendix' + self.file_suffix)
deprecated_extensions_appendix_fp = self.newFile(self.directory + '/deprecated_extensions_appendix' + self.file_suffix)
current_extension_appendices_fp = self.newFile(self.directory + '/current_extension_appendices' + self.file_suffix)
current_extension_appendices_toc_fp = self.newFile(self.directory + '/current_extension_appendices_toc' + self.file_suffix)
deprecated_extension_appendices_fp = self.newFile(self.directory + '/deprecated_extension_appendices' + self.file_suffix)
deprecated_extension_appendices_toc_fp = self.newFile(self.directory + '/deprecated_extension_appendices_toc' + self.file_suffix)
deprecated_extensions_guard_macro_fp = self.newFile(self.directory + '/deprecated_extensions_guard_macro' + self.file_suffix)
provisional_extensions_appendix_fp = self.newFile(self.directory + '/provisional_extensions_appendix' + self.file_suffix)
provisional_extension_appendices_fp = self.newFile(self.directory + '/provisional_extension_appendices' + self.file_suffix)
provisional_extension_appendices_toc_fp = self.newFile(self.directory + '/provisional_extension_appendices_toc' + self.file_suffix)
provisional_extensions_guard_macro_fp = self.newFile(self.directory + '/provisional_extensions_guard_macro' + self.file_suffix)
write('include::deprecated_extensions_guard_macro' + self.file_suffix + '[]', file=current_extensions_appendix_fp)
write('', file=current_extensions_appendix_fp)
write('ifndef::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp)
write('[[extension-appendices-list]]', file=current_extensions_appendix_fp)
write('== List of Extensions', file=current_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp)
write('ifdef::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp)
write('[[extension-appendices-list]]', file=current_extensions_appendix_fp)
write('== List of Current Extensions', file=current_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp)
write('', file=current_extensions_appendix_fp)
write('include::current_extension_appendices_toc' + self.file_suffix + '[]', file=current_extensions_appendix_fp)
write('<<<', file=current_extensions_appendix_fp)
write('include::current_extension_appendices' + self.file_suffix + '[]', file=current_extensions_appendix_fp)
write('include::deprecated_extensions_guard_macro' + self.file_suffix + '[]', file=deprecated_extensions_appendix_fp)
write('', file=deprecated_extensions_appendix_fp)
write('ifdef::HAS_DEPRECATED_EXTENSIONS[]', file=deprecated_extensions_appendix_fp)
write('[[deprecated-extension-appendices-list]]', file=deprecated_extensions_appendix_fp)
write('== List of Deprecated Extensions', file=deprecated_extensions_appendix_fp)
write('include::deprecated_extension_appendices_toc' + self.file_suffix + '[]', file=deprecated_extensions_appendix_fp)
write('<<<', file=deprecated_extensions_appendix_fp)
write('include::deprecated_extension_appendices' + self.file_suffix + '[]', file=deprecated_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]', file=deprecated_extensions_appendix_fp)
# add include guard to allow multiple includes
write('ifndef::DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]', file=deprecated_extensions_guard_macro_fp)
write(':DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD:\n', file=deprecated_extensions_guard_macro_fp)
write('ifndef::PROVISIONAL_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]', file=provisional_extensions_guard_macro_fp)
write(':PROVISIONAL_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD:\n', file=provisional_extensions_guard_macro_fp)
write('include::provisional_extensions_guard_macro' + self.file_suffix + '[]', file=provisional_extensions_appendix_fp)
write('', file=provisional_extensions_appendix_fp)
write('ifdef::HAS_PROVISIONAL_EXTENSIONS[]', file=provisional_extensions_appendix_fp)
write('[[provisional-extension-appendices-list]]', file=provisional_extensions_appendix_fp)
write('== List of Provisional Extensions', file=provisional_extensions_appendix_fp)
write('include::provisional_extension_appendices_toc' + self.file_suffix + '[]', file=provisional_extensions_appendix_fp)
write('<<<', file=provisional_extensions_appendix_fp)
write('include::provisional_extension_appendices' + self.file_suffix + '[]', file=provisional_extensions_appendix_fp)
write('endif::HAS_PROVISIONAL_EXTENSIONS[]', file=provisional_extensions_appendix_fp)
for ext in self.extensions:
include = 'include::../' + ext.name + self.file_suffix + '[]'
link = ' * <<' + ext.name + '>>'
if ext.provisional == 'true':
write(self.conditionalExt(ext.name, include), file=provisional_extension_appendices_fp)
write(self.conditionalExt(ext.name, link), file=provisional_extension_appendices_toc_fp)
write(self.conditionalExt(ext.name, ':HAS_PROVISIONAL_EXTENSIONS:'), file=provisional_extensions_guard_macro_fp)
elif ext.deprecationType is None:
write(self.conditionalExt(ext.name, include), file=current_extension_appendices_fp)
write(self.conditionalExt(ext.name, link), file=current_extension_appendices_toc_fp)
else:
condition = ext.supercedingAPIVersion if ext.supercedingAPIVersion else ext.supercedingExtension # potentially None too
write(self.conditionalExt(ext.name, include, 'ifndef', condition), file=current_extension_appendices_fp)
write(self.conditionalExt(ext.name, link, 'ifndef', condition), file=current_extension_appendices_toc_fp)
write(self.conditionalExt(ext.name, include, 'ifdef', condition), file=deprecated_extension_appendices_fp)
write(self.conditionalExt(ext.name, link, 'ifdef', condition), file=deprecated_extension_appendices_toc_fp)
write(self.conditionalExt(ext.name, ':HAS_DEPRECATED_EXTENSIONS:', 'ifdef', condition), file=deprecated_extensions_guard_macro_fp)
current_extensions_appendix_fp.close()
deprecated_extensions_appendix_fp.close()
current_extension_appendices_fp.close()
current_extension_appendices_toc_fp.close()
deprecated_extension_appendices_fp.close()
deprecated_extension_appendices_toc_fp.close()
write('endif::DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]', file=deprecated_extensions_guard_macro_fp)
deprecated_extensions_guard_macro_fp.close()
OutputGenerator.endFile(self)
def endFile(self):
self.extensions.sort()
for ext in self.extensions:
ext.makeMetafile(self.extensions)
promotedExtensions = {}
for ext in self.extensions:
if ext.deprecationType == 'promotion' and ext.supercedingAPIVersion:
promotedExtensions.setdefault(ext.supercedingAPIVersion, []).append(ext)
for coreVersion, extensions in promotedExtensions.items():
promoted_extensions_fp = self.newFile(self.directory + '/promoted_extensions_' + coreVersion + self.file_suffix)
for ext in extensions:
indent = ''
write(' * {blank}\n+\n' + ext.conditionalLinkExt(ext.name, indent), file=promoted_extensions_fp)
promoted_extensions_fp.close()
current_extensions_appendix_fp = self.newFile(self.directory + '/current_extensions_appendix' + self.file_suffix)
deprecated_extensions_appendix_fp = self.newFile(self.directory + '/deprecated_extensions_appendix' + self.file_suffix)
current_extension_appendices_fp = self.newFile(self.directory + '/current_extension_appendices' + self.file_suffix)
current_extension_appendices_toc_fp = self.newFile(self.directory + '/current_extension_appendices_toc' + self.file_suffix)
deprecated_extension_appendices_fp = self.newFile(self.directory + '/deprecated_extension_appendices' + self.file_suffix)
deprecated_extension_appendices_toc_fp = self.newFile(self.directory + '/deprecated_extension_appendices_toc' + self.file_suffix)
deprecated_extensions_guard_macro_fp = self.newFile(self.directory + '/deprecated_extensions_guard_macro' + self.file_suffix)
provisional_extensions_appendix_fp = self.newFile(self.directory + '/provisional_extensions_appendix' + self.file_suffix)
provisional_extension_appendices_fp = self.newFile(self.directory + '/provisional_extension_appendices' + self.file_suffix)
provisional_extension_appendices_toc_fp = self.newFile(self.directory + '/provisional_extension_appendices_toc' + self.file_suffix)
provisional_extensions_guard_macro_fp = self.newFile(self.directory + '/provisional_extensions_guard_macro' + self.file_suffix)
write('include::deprecated_extensions_guard_macro' + self.file_suffix + '[]', file=current_extensions_appendix_fp)
write('', file=current_extensions_appendix_fp)
write('ifndef::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp)
write('[[extension-appendices-list]]', file=current_extensions_appendix_fp)
write('== List of Extensions', file=current_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp)
write('ifdef::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp)
write('[[extension-appendices-list]]', file=current_extensions_appendix_fp)
write('== List of Current Extensions', file=current_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]', file=current_extensions_appendix_fp)
write('', file=current_extensions_appendix_fp)
write('include::current_extension_appendices_toc' + self.file_suffix + '[]', file=current_extensions_appendix_fp)
write('<<<', file=current_extensions_appendix_fp)
write('include::current_extension_appendices' + self.file_suffix + '[]', file=current_extensions_appendix_fp)
write('include::deprecated_extensions_guard_macro' + self.file_suffix + '[]', file=deprecated_extensions_appendix_fp)
write('', file=deprecated_extensions_appendix_fp)
write('ifdef::HAS_DEPRECATED_EXTENSIONS[]', file=deprecated_extensions_appendix_fp)
write('[[deprecated-extension-appendices-list]]', file=deprecated_extensions_appendix_fp)
write('== List of Deprecated Extensions', file=deprecated_extensions_appendix_fp)
write('include::deprecated_extension_appendices_toc' + self.file_suffix + '[]', file=deprecated_extensions_appendix_fp)
write('<<<', file=deprecated_extensions_appendix_fp)
write('include::deprecated_extension_appendices' + self.file_suffix + '[]', file=deprecated_extensions_appendix_fp)
write('endif::HAS_DEPRECATED_EXTENSIONS[]', file=deprecated_extensions_appendix_fp)
# add include guard to allow multiple includes
write('ifndef::DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]', file=deprecated_extensions_guard_macro_fp)
write(':DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD:\n', file=deprecated_extensions_guard_macro_fp)
write('ifndef::PROVISIONAL_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]', file=provisional_extensions_guard_macro_fp)
write(':PROVISIONAL_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD:\n', file=provisional_extensions_guard_macro_fp)
write('include::provisional_extensions_guard_macro' + self.file_suffix + '[]', file=provisional_extensions_appendix_fp)
write('', file=provisional_extensions_appendix_fp)
write('ifdef::HAS_PROVISIONAL_EXTENSIONS[]', file=provisional_extensions_appendix_fp)
write('[[provisional-extension-appendices-list]]', file=provisional_extensions_appendix_fp)
write('== List of Provisional Extensions', file=provisional_extensions_appendix_fp)
write('include::provisional_extension_appendices_toc' + self.file_suffix + '[]', file=provisional_extensions_appendix_fp)
write('<<<', file=provisional_extensions_appendix_fp)
write('include::provisional_extension_appendices' + self.file_suffix + '[]', file=provisional_extensions_appendix_fp)
write('endif::HAS_PROVISIONAL_EXTENSIONS[]', file=provisional_extensions_appendix_fp)
for ext in self.extensions:
include = 'include::../' + ext.name + self.file_suffix + '[]'
link = ' * <<' + ext.name + '>>'
if ext.provisional == 'true':
write(self.conditionalExt(ext.name, include), file=provisional_extension_appendices_fp)
write(self.conditionalExt(ext.name, link), file=provisional_extension_appendices_toc_fp)
write(self.conditionalExt(ext.name, ':HAS_PROVISIONAL_EXTENSIONS:'), file=provisional_extensions_guard_macro_fp)
elif ext.deprecationType is None:
write(self.conditionalExt(ext.name, include), file=current_extension_appendices_fp)
write(self.conditionalExt(ext.name, link), file=current_extension_appendices_toc_fp)
else:
condition = ext.supercedingAPIVersion if ext.supercedingAPIVersion else ext.supercedingExtension # potentially None too
write(self.conditionalExt(ext.name, include, 'ifndef', condition), file=current_extension_appendices_fp)
write(self.conditionalExt(ext.name, link, 'ifndef', condition), file=current_extension_appendices_toc_fp)
write(self.conditionalExt(ext.name, include, 'ifdef', condition), file=deprecated_extension_appendices_fp)
write(self.conditionalExt(ext.name, link, 'ifdef', condition), file=deprecated_extension_appendices_toc_fp)
write(self.conditionalExt(ext.name, ':HAS_DEPRECATED_EXTENSIONS:', 'ifdef', condition), file=deprecated_extensions_guard_macro_fp)
current_extensions_appendix_fp.close()
deprecated_extensions_appendix_fp.close()
current_extension_appendices_fp.close()
current_extension_appendices_toc_fp.close()
deprecated_extension_appendices_fp.close()
deprecated_extension_appendices_toc_fp.close()
write('endif::DEPRECATED_EXTENSIONS_GUARD_MACRO_INCLUDE_GUARD[]', file=deprecated_extensions_guard_macro_fp)
deprecated_extensions_guard_macro_fp.close()
OutputGenerator.endFile(self)
def endFile(self):
OutputGenerator.endFile(self)
