3 # Copyright (c) 2013-2014 The Khronos Group Inc.
5 # Permission is hereby granted, free of charge, to any person obtaining a
6 # copy of this software and/or associated documentation files (the
7 # "Materials"), to deal in the Materials without restriction, including
8 # without limitation the rights to use, copy, modify, merge, publish,
9 # distribute, sublicense, and/or sell copies of the Materials, and to
10 # permit persons to whom the Materials are furnished to do so, subject to
11 # the following conditions:
13 # The above copyright notice and this permission notice shall be included
14 # in all copies or substantial portions of the Materials.
16 # THE MATERIALS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
17 # EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
18 # MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
19 # IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
20 # CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
21 # TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
22 # MATERIALS OR THE USE OR OTHER DEALINGS IN THE MATERIALS.
24 import io,os,re,string,sys
25 from lxml import etree
27 def write( *args, **kwargs ):
28 file = kwargs.pop('file',sys.stdout)
29 end = kwargs.pop( 'end','\n')
30 file.write( ' '.join([str(arg) for arg in args]) )
33 # noneStr - returns string argument, or "" if argument is None.
34 # Used in converting lxml Elements into text.
35 # str - string to convert
42 # matchAPIProfile - returns whether an API and profile
43 # being generated matches an element's profile
44 # api - string naming the API to match
45 # profile - string naming the profile to match
46 # elem - Element which (may) have 'api' and 'profile'
47 # attributes to match to.
48 # If a tag is not present in the Element, the corresponding API
49 # or profile always matches.
50 # Otherwise, the tag must exactly match the API or profile.
51 # Thus, if 'profile' = core:
52 # <remove> with no attribute will match
53 # <remove profile='core'> will match
54 # <remove profile='compatibility'> will not match
55 # Possible match conditions:
59 # None None Always matches
60 # 'string' None Always matches
61 # None 'string' Does not match. Can't generate multiple APIs
62 # or profiles, so if an API/profile constraint
63 # is present, it must be asked for explicitly.
64 # 'string' 'string' Strings must match
66 # ** In the future, we will allow regexes for the attributes,
67 # not just strings, so that api="^(gl|gles2)" will match. Even
68 # this isn't really quite enough, we might prefer something
69 # like "gl(core)|gles1(common-lite)".
70 def matchAPIProfile(api, profile, elem):
71 """Match a requested API & profile name to a api & profile attributes of an Element"""
73 # Match 'api', if present
74 if ('api' in elem.attrib):
76 raise UserWarning("No API requested, but 'api' attribute is present with value '" +
77 elem.get('api') + "'")
78 elif (api != elem.get('api')):
79 # Requested API doesn't match attribute
81 if ('profile' in elem.attrib):
83 raise UserWarning("No profile requested, but 'profile' attribute is present with value '" +
84 elem.get('profile') + "'")
85 elif (profile != elem.get('profile')):
86 # Requested profile doesn't match attribute
90 # BaseInfo - base class for information about a registry feature
91 # (type/group/enum/command/API/extension).
92 # required - should this feature be defined during header generation
93 # (has it been removed by a profile or version)?
94 # declared - has this feature been defined already?
95 # elem - lxml.etree Element for this feature
96 # resetState() - reset required/declared to initial values. Used
97 # prior to generating a new API interface.
99 """Represents the state of a registry feature, used during API generation"""
100 def __init__(self, elem):
101 self.required = False
102 self.declared = False
104 def resetState(self):
105 self.required = False
106 self.declared = False
108 # TypeInfo - registry information about a type. No additional state
109 # beyond BaseInfo is required.
110 class TypeInfo(BaseInfo):
111 """Represents the state of a registry type"""
112 def __init__(self, elem):
113 BaseInfo.__init__(self, elem)
115 # GroupInfo - registry information about a group of related enums.
116 # enums - dictionary of enum names which are in the group
117 class GroupInfo(BaseInfo):
118 """Represents the state of a registry enumerant group"""
119 def __init__(self, elem):
120 BaseInfo.__init__(self, elem)
123 # EnumInfo - registry information about an enum
124 # type - numeric type of the value of the <enum> tag
125 # ( '' for GLint, 'u' for GLuint, 'ull' for GLuint64 )
126 class EnumInfo(BaseInfo):
127 """Represents the state of a registry enum"""
128 def __init__(self, elem):
129 BaseInfo.__init__(self, elem)
130 self.type = elem.get('type')
131 if (self.type == None):
134 # CmdInfo - registry information about a command
135 # glxtype - type of GLX protocol { None, 'render', 'single', 'vendor' }
136 # glxopcode - GLX protocol opcode { None, number }
137 # glxequiv - equivalent command at GLX dispatch level { None, string }
138 # vecequiv - equivalent vector form of a command taking multiple scalar args
140 class CmdInfo(BaseInfo):
141 """Represents the state of a registry command"""
142 def __init__(self, elem):
143 BaseInfo.__init__(self, elem)
145 self.glxopcode = None
149 # FeatureInfo - registry information about an API <feature>
151 # name - feature name string (e.g. 'GL_ARB_multitexture')
152 # number - feature version number (e.g. 1.2). <extension>
153 # features are unversioned and assigned version number 0.
154 # category - category, e.g. VERSION or ARB/KHR/OES/ETC/vendor
155 # emit - has this feature been defined already?
156 class FeatureInfo(BaseInfo):
157 """Represents the state of an API feature (version/extension)"""
158 def __init__(self, elem):
159 BaseInfo.__init__(self, elem)
160 self.name = elem.get('name')
161 # Determine element category (vendor). Only works
162 # for <extension> elements.
163 if (elem.tag == 'feature'):
164 self.category = 'VERSION'
165 self.number = elem.get('number')
167 self.category = self.name.split('_', 2)[1]
171 # Primary sort key for regSortFeatures.
172 # Sorts by category of the feature name string:
173 # Core API features (those defined with a <feature> tag)
174 # ARB/KHR/OES (Khronos extensions)
175 # other (EXT/vendor extensions)
176 def regSortCategoryKey(feature):
177 if (feature.elem.tag == 'feature'):
179 elif (feature.category == 'ARB' or
180 feature.category == 'KHR' or
181 feature.category == 'OES'):
186 # Secondary sort key for regSortFeatures.
187 # Sorts by extension name.
188 def regSortNameKey(feature):
191 # Tertiary sort key for regSortFeatures.
192 # Sorts by feature version number. <extension>
193 # elements all have version number "0"
194 def regSortNumberKey(feature):
195 return feature.number
197 # regSortFeatures - default sort procedure for features.
198 # Sorts by primary key of feature category,
199 # then by feature name within the category,
200 # then by version number
201 def regSortFeatures(featureList):
202 featureList.sort(key = regSortNumberKey)
203 featureList.sort(key = regSortNameKey)
204 featureList.sort(key = regSortCategoryKey)
206 # GeneratorOptions - base class for options used during header production
207 # These options are target language independent, and used by
208 # Registry.apiGen() and by base OutputGenerator objects.
211 # filename - name of file to generate, or None to write to stdout.
212 # apiname - string matching <api> 'apiname' attribute, e.g. 'gl'.
213 # profile - string specifying API profile , e.g. 'core', or None.
214 # versions - regex matching API versions to process interfaces for.
215 # Normally '.*' or '[0-9]\.[0-9]' to match all defined versions.
216 # emitversions - regex matching API versions to actually emit
217 # interfaces for (though all requested versions are considered
218 # when deciding which interfaces to generate). For GL 4.3 glext.h,
219 # this might be '1\.[2-5]|[2-4]\.[0-9]'.
220 # defaultExtensions - If not None, a string which must in its
221 # entirety match the pattern in the "supported" attribute of
222 # the <extension>. Defaults to None. Usually the same as apiname.
223 # addExtensions - regex matching names of additional extensions
224 # to include. Defaults to None.
225 # removeExtenions - regex matching names of extensions to
226 # remove (after defaultExtensions and addExtensions). Defaults
228 # sortProcedure - takes a list of FeatureInfo objects and sorts
229 # them in place to a preferred order in the generated output.
230 # Default is core API versions, ARB/KHR/OES extensions, all
231 # other extensions, alphabetically within each group.
232 # The regex patterns can be None or empty, in which case they match
234 class GeneratorOptions:
235 """Represents options during header production from an API registry"""
242 defaultExtensions = None,
243 addExtensions = None,
244 removeExtensions = None,
245 sortProcedure = regSortFeatures):
246 self.filename = filename
247 self.apiname = apiname
248 self.profile = profile
249 self.versions = self.emptyRegex(versions)
250 self.emitversions = self.emptyRegex(emitversions)
251 self.defaultExtensions = defaultExtensions
252 self.addExtensions = self.emptyRegex(addExtensions)
253 self.removeExtensions = self.emptyRegex(removeExtensions)
254 self.sortProcedure = sortProcedure
256 # Substitute a regular expression which matches no version
257 # or extension names for None or the empty string.
258 def emptyRegex(self,pat):
259 if (pat == None or pat == ''):
264 # CGeneratorOptions - subclass of GeneratorOptions.
266 # Adds options used by COutputGenerator objects during C language header
270 # prefixText - list of strings to prefix generated header with
271 # (usually a copyright statement + calling convention macros).
272 # protectFile - True if multiple inclusion protection should be
273 # generated (based on the filename) around the entire header.
274 # protectFeature - True if #ifndef..#endif protection should be
275 # generated around a feature interface in the header file.
276 # genFuncPointers - True if function pointer typedefs should be
278 # protectProto - True if #ifdef..#endif protection should be
279 # generated around prototype declarations
280 # protectProtoStr - #ifdef symbol to use around prototype
281 # declarations, if protected
282 # apicall - string to use for the function declaration prefix,
283 # such as APICALL on Windows.
284 # apientry - string to use for the calling convention macro,
285 # in typedefs, such as APIENTRY.
286 # apientryp - string to use for the calling convention macro
287 # in function pointer typedefs, such as APIENTRYP.
288 class CGeneratorOptions(GeneratorOptions):
289 """Represents options during C header production from an API registry"""
296 defaultExtensions = None,
297 addExtensions = None,
298 removeExtensions = None,
299 sortProcedure = regSortFeatures,
301 genFuncPointers = True,
303 protectFeature = True,
305 protectProtoStr = True,
309 GeneratorOptions.__init__(self, filename, apiname, profile,
310 versions, emitversions, defaultExtensions,
311 addExtensions, removeExtensions, sortProcedure)
312 self.prefixText = prefixText
313 self.genFuncPointers = genFuncPointers
314 self.protectFile = protectFile
315 self.protectFeature = protectFeature
316 self.protectProto = protectProto
317 self.protectProtoStr = protectProtoStr
318 self.apicall = apicall
319 self.apientry = apientry
320 self.apientryp = apientryp
322 # OutputGenerator - base class for generating API interfaces.
323 # Manages basic logic, logging, and output file control
324 # Derived classes actually generate formatted output.
327 # OutputGenerator(errFile, warnFile, diagFile)
328 # errFile, warnFile, diagFile - file handles to write errors,
329 # warnings, diagnostics to. May be None to not write.
330 # logMsg(level, *args) - log messages of different categories
331 # level - 'error', 'warn', or 'diag'. 'error' will also
332 # raise a UserWarning exception
333 # *args - print()-style arguments
334 # beginFile(genOpts) - start a new interface file
335 # genOpts - GeneratorOptions controlling what's generated and how
336 # endFile() - finish an interface file, closing it when done
337 # beginFeature(interface, emit) - write interface for a feature
338 # and tag generated features as having been done.
339 # interface - element for the <version> / <extension> to generate
340 # emit - actually write to the header only when True
341 # endFeature() - finish an interface.
342 # genType(typeinfo,name) - generate interface for a type
343 # typeinfo - TypeInfo for a type
344 # genEnum(enuminfo, name) - generate interface for an enum
345 # enuminfo - EnumInfo for an enum
347 # genCmd(cmdinfo) - generate interface for a command
348 # cmdinfo - CmdInfo for a command
349 class OutputGenerator:
350 """Generate specified API interfaces in a specific style, such as a C header"""
352 errFile = sys.stderr,
353 warnFile = sys.stderr,
354 diagFile = sys.stdout):
356 self.errFile = errFile
357 self.warnFile = warnFile
358 self.diagFile = diagFile
360 self.featureName = None
363 # logMsg - write a message of different categories to different
366 # 'diag' (diagnostic, voluminous)
368 # 'error' (fatal error - raises exception after logging)
369 # *args - print()-style arguments to direct to corresponding log
370 def logMsg(self, level, *args):
371 """Log a message at the given level. Can be ignored or log to a file"""
372 if (level == 'error'):
373 strfile = io.StringIO()
374 write('ERROR:', *args, file=strfile)
375 if (self.errFile != None):
376 write(strfile.getvalue(), file=self.errFile)
377 raise UserWarning(strfile.getvalue())
378 elif (level == 'warn'):
379 if (self.warnFile != None):
380 write('WARNING:', *args, file=self.warnFile)
381 elif (level == 'diag'):
382 if (self.diagFile != None):
383 write('DIAG:', *args, file=self.diagFile)
386 '*** FATAL ERROR in Generator.logMsg: unknown level:' + level)
388 def beginFile(self, genOpts):
389 self.genOpts = genOpts
391 # Open specified output file. Not done in constructor since a
392 # Generator can be used without writing to a file.
393 if (self.genOpts.filename != None):
394 self.outFile = open(self.genOpts.filename, 'w')
396 self.outFile = sys.stdout
398 self.errFile and self.errFile.flush()
399 self.warnFile and self.warnFile.flush()
400 self.diagFile and self.diagFile.flush()
402 if (self.outFile != sys.stdout and self.outFile != sys.stderr):
406 def beginFeature(self, interface, emit):
408 self.featureName = interface.get('name')
409 # If there's an additional 'protect' attribute in the feature, save it
410 self.featureExtraProtect = interface.get('protect')
411 def endFeature(self):
412 # Derived classes responsible for emitting feature
413 self.featureName = None
414 self.featureExtraProtect = None
417 def genType(self, typeinfo, name):
418 if (self.featureName == None):
419 raise UserWarning('Attempt to generate type', name,
420 'when not in feature')
422 # Enumerant generation
423 def genEnum(self, enuminfo, name):
424 if (self.featureName == None):
425 raise UserWarning('Attempt to generate enum', name,
426 'when not in feature')
429 def genCmd(self, cmd, name):
430 if (self.featureName == None):
431 raise UserWarning('Attempt to generate command', name,
432 'when not in feature')
434 # COutputGenerator - subclass of OutputGenerator.
435 # Generates C-language API interfaces.
438 # COutputGenerator(errFile, warnFile, diagFile) - args as for
439 # OutputGenerator. Defines additional internal state.
440 # makeCDecls(cmd) - return C prototype and function pointer typedef for a
441 # <command> Element, as a list of two strings
442 # cmd - Element for the <command>
443 # newline() - print a newline to the output file (utility function)
444 # ---- methods overriding base class ----
447 # beginFeature(interface, emit)
449 # genType(typeinfo,name) - generate interface for a type
450 # genEnum(enuminfo, name)
452 class COutputGenerator(OutputGenerator):
453 """Generate specified API interfaces in a specific style, such as a C header"""
455 errFile = sys.stderr,
456 warnFile = sys.stderr,
457 diagFile = sys.stdout):
458 OutputGenerator.__init__(self, errFile, warnFile, diagFile)
459 # Internal state - accumulators for different inner block text
464 # makeCDecls - return C prototype and function pointer typedef for a
465 # command, as a two-element list of strings.
466 # cmd - Element containing a <command> tag
467 def makeCDecls(self, cmd):
468 """Generate C function pointer typedef for <command> Element"""
469 proto = cmd.find('proto')
470 params = cmd.findall('param')
471 # Begin accumulating prototype and typedef strings
472 pdecl = self.genOpts.apicall
475 # Insert the function return type/name.
476 # For prototypes, add APIENTRY macro before the name
477 # For typedefs, add (APIENTRYP <name>) around the name and
478 # use the PFNGLCMDNAMEPROC nameng convention.
479 # Done by walking the tree for <proto> element by element.
480 # lxml.etree has elem.text followed by (elem[i], elem[i].tail)
481 # for each child element and any following text
483 pdecl += noneStr(proto.text)
484 tdecl += noneStr(proto.text)
485 # For each child element, if it's a <name> wrap in appropriate
486 # declaration. Otherwise append its contents and tail contents.
488 text = noneStr(elem.text)
489 tail = noneStr(elem.tail)
490 if (elem.tag == 'name'):
491 pdecl += self.genOpts.apientry + text + tail
492 tdecl += '(' + self.genOpts.apientryp + 'PFN' + text.upper() + 'PROC' + tail + ')'
496 # Now add the parameter declaration list, which is identical
497 # for prototypes and typedefs. Concatenate all the text from
498 # a <param> node without the tags. No tree walking required
499 # since all tags are ignored.
504 paramdecl += ''.join([t for t in params[i].itertext()])
510 return [ pdecl + paramdecl, tdecl + paramdecl ]
513 write('', file=self.outFile)
515 def beginFile(self, genOpts):
516 OutputGenerator.beginFile(self, genOpts)
519 # Multiple inclusion protection & C++ wrappers.
520 if (genOpts.protectFile and self.genOpts.filename):
521 headerSym = '__' + re.sub('\.h', '_h_', os.path.basename(self.genOpts.filename))
522 write('#ifndef', headerSym, file=self.outFile)
523 write('#define', headerSym, '1', file=self.outFile)
525 write('#ifdef __cplusplus', file=self.outFile)
526 write('extern "C" {', file=self.outFile)
527 write('#endif', file=self.outFile)
530 # User-supplied prefix text, if any (list of strings)
531 if (genOpts.prefixText):
532 for s in genOpts.prefixText:
533 write(s, file=self.outFile)
535 # Some boilerplate describing what was generated - this
536 # will probably be removed later since the extensions
537 # pattern may be very long.
538 write('/* Generated C header for:', file=self.outFile)
539 write(' * API:', genOpts.apiname, file=self.outFile)
540 if (genOpts.profile):
541 write(' * Profile:', genOpts.profile, file=self.outFile)
542 write(' * Versions considered:', genOpts.versions, file=self.outFile)
543 write(' * Versions emitted:', genOpts.emitversions, file=self.outFile)
544 write(' * Default extensions included:', genOpts.defaultExtensions, file=self.outFile)
545 write(' * Additional extensions included:', genOpts.addExtensions, file=self.outFile)
546 write(' * Extensions removed:', genOpts.removeExtensions, file=self.outFile)
547 write(' */', file=self.outFile)
550 # Finish C++ wrapper and multiple inclusion protection
552 write('#ifdef __cplusplus', file=self.outFile)
553 write('}', file=self.outFile)
554 write('#endif', file=self.outFile)
555 if (self.genOpts.protectFile and self.genOpts.filename):
557 write('#endif', file=self.outFile)
558 # Finish processing in superclass
559 OutputGenerator.endFile(self)
560 def beginFeature(self, interface, emit):
561 # Start processing in superclass
562 OutputGenerator.beginFeature(self, interface, emit)
564 # Accumulate types, enums, function pointer typedefs, end function
565 # prototypes separately for this feature. They're only printed in
569 self.cmdPointerBody = ''
571 def endFeature(self):
573 # Actually write the interface to the output file.
576 if (self.genOpts.protectFeature):
577 write('#ifndef', self.featureName, file=self.outFile)
578 write('#define', self.featureName, '1', file=self.outFile)
579 if (self.typeBody != ''):
580 write(self.typeBody, end='', file=self.outFile)
582 # Don't add additional protection for derived type declarations,
583 # which may be needed by other features later on.
584 if (self.featureExtraProtect != None):
585 write('#ifdef', self.featureExtraProtect, file=self.outFile)
586 if (self.enumBody != ''):
587 write(self.enumBody, end='', file=self.outFile)
588 if (self.genOpts.genFuncPointers and self.cmdPointerBody != ''):
589 write(self.cmdPointerBody, end='', file=self.outFile)
590 if (self.cmdBody != ''):
591 if (self.genOpts.protectProto):
592 write('#ifdef', self.genOpts.protectProtoStr, file=self.outFile)
593 write(self.cmdBody, end='', file=self.outFile)
594 if (self.genOpts.protectProto):
595 write('#endif', file=self.outFile)
596 if (self.featureExtraProtect != None):
597 write('#endif /*', self.featureExtraProtect, '*/', file=self.outFile)
598 if (self.genOpts.protectFeature):
599 write('#endif /*', self.featureName, '*/', file=self.outFile)
600 # Finish processing in superclass
601 OutputGenerator.endFeature(self)
604 def genType(self, typeinfo, name):
605 OutputGenerator.genType(self, typeinfo, name)
607 # Replace <apientry /> tags with an APIENTRY-style string
608 # (from self.genOpts). Copy other text through unchanged.
609 # If the resulting text is an empty string, don't emit it.
610 typeElem = typeinfo.elem
611 s = noneStr(typeElem.text)
612 for elem in typeElem:
613 if (elem.tag == 'apientry'):
614 s += self.genOpts.apientry + noneStr(elem.tail)
616 s += noneStr(elem.text) + noneStr(elem.tail)
618 self.typeBody += s + "\n"
620 # Enumerant generation
621 def genEnum(self, enuminfo, name):
622 OutputGenerator.genEnum(self, enuminfo, name)
624 # EnumInfo.type is a C value suffix (e.g. u, ull)
625 self.enumBody += '#define ' + name.ljust(33) + ' ' + enuminfo.elem.get('value')
627 # Handle non-integer 'type' fields by using it as the C value suffix
628 t = enuminfo.elem.get('type')
629 if (t != '' and t != 'i'):
630 self.enumBody += enuminfo.type
631 self.enumBody += "\n"
634 def genCmd(self, cmdinfo, name):
635 OutputGenerator.genCmd(self, cmdinfo, name)
637 decls = self.makeCDecls(cmdinfo.elem)
638 self.cmdBody += decls[0]
639 if (self.genOpts.genFuncPointers):
640 self.cmdPointerBody += decls[1]
642 # Registry - object representing an API registry, loaded from an XML file
644 # tree - ElementTree containing the root <registry>
645 # typedict - dictionary of TypeInfo objects keyed by type name
646 # groupdict - dictionary of GroupInfo objects keyed by group name
647 # enumdict - dictionary of EnumInfo objects keyed by enum name
648 # cmddict - dictionary of CmdInfo objects keyed by command name
649 # apidict - dictionary of <api> Elements keyed by API name
650 # extensions - list of <extension> Elements
651 # extdict - dictionary of <extension> Elements keyed by extension name
652 # gen - OutputGenerator object used to write headers / messages
653 # genOpts - GeneratorOptions object used to control which
654 # fetures to write and how to format them
655 # emitFeatures - True to actually emit features for a version / extension,
656 # or False to just treat them as emitted
658 # loadElementTree(etree) - load registry from specified ElementTree
659 # loadFile(filename) - load registry from XML file
660 # setGenerator(gen) - OutputGenerator to use
661 # parseTree() - parse the registry once loaded & create dictionaries
662 # dumpReg(maxlen, filehandle) - diagnostic to dump the dictionaries
663 # to specified file handle (default stdout). Truncates type /
664 # enum / command elements to maxlen characters (default 80)
665 # generator(g) - specify the output generator object
666 # apiGen(apiname, genOpts) - generate API headers for the API type
667 # and profile specified in genOpts, but only for the versions and
668 # extensions specified there.
669 # apiReset() - call between calls to apiGen() to reset internal state
670 # validateGroups() - call to verify that each <proto> or <param>
671 # with a 'group' attribute matches an actual existing group.
673 # addElementInfo(elem,info,infoName,dictionary) - add feature info to dict
674 # lookupElementInfo(fname,dictionary) - lookup feature info in dict
676 """Represents an API registry loaded from XML"""
686 # A default output generator, so commands prior to apiGen can report
687 # errors via the generator object.
688 self.gen = OutputGenerator()
690 self.emitFeatures = False
691 def loadElementTree(self, tree):
692 """Load ElementTree into a Registry object and parse it"""
695 def loadFile(self, file):
696 """Load an API registry XML file into a Registry object and parse it"""
697 self.tree = etree.parse(file)
699 def setGenerator(self, gen):
700 """Specify output generator object. None restores the default generator"""
702 # addElementInfo - add information about an element to the
703 # corresponding dictionary
704 # elem - <type>/<group>/<enum>/<command>/<feature>/<extension> Element
705 # info - corresponding {Type|Group|Enum|Cmd|Feature}Info object
706 # infoName - 'type' / 'group' / 'enum' / 'command' / 'feature' / 'extension'
707 # dictionary - self.{type|group|enum|cmd|api|ext}dict
708 # If the Element has an 'api' attribute, the dictionary key is the
709 # tuple (name,api). If not, the key is the name. 'name' is an
710 # attribute of the Element
711 def addElementInfo(self, elem, info, infoName, dictionary):
712 if ('api' in elem.attrib):
713 key = (elem.get('name'),elem.get('api'))
715 key = elem.get('name')
716 if key in dictionary:
717 self.gen.logMsg('warn', '*** Attempt to redefine',
718 infoName, 'with key:', key)
720 dictionary[key] = info
722 # lookupElementInfo - find a {Type|Enum|Cmd}Info object by name.
723 # If an object qualified by API name exists, use that.
724 # fname - name of type / enum / command
725 # dictionary - self.{type|enum|cmd}dict
726 def lookupElementInfo(self, fname, dictionary):
727 key = (fname, self.genOpts.apiname)
728 if (key in dictionary):
729 # self.gen.logMsg('diag', 'Found API-specific element for feature', fname)
730 return dictionary[key]
731 elif (fname in dictionary):
732 # self.gen.logMsg('diag', 'Found generic element for feature', fname)
733 return dictionary[fname]
737 """Parse the registry Element, once created"""
738 # This must be the Element for the root <registry>
739 self.reg = self.tree.getroot()
741 # Create dictionary of registry types from toplevel <types> tags
742 # and add 'name' attribute to each <type> tag (where missing)
743 # based on its <name> element.
745 # There's usually one <types> block; more are OK
746 # Required <type> attributes: 'name' or nested <name> tag contents
748 for type in self.reg.findall('types/type'):
749 # If the <type> doesn't already have a 'name' attribute, set
750 # it from contents of its <name> tag.
751 if (type.get('name') == None):
752 type.attrib['name'] = type.find('name').text
753 self.addElementInfo(type, TypeInfo(type), 'type', self.typedict)
755 # Create dictionary of registry groups from toplevel <groups> tags.
757 # There's usually one <groups> block; more are OK.
758 # Required <group> attributes: 'name'
760 for group in self.reg.findall('groups/group'):
761 self.addElementInfo(group, GroupInfo(group), 'group', self.groupdict)
763 # Create dictionary of registry enums from toplevel <enums> tags
765 # There are usually many <enums> tags in different namespaces, but
766 # these are functional namespaces of the values, while the actual
767 # enum names all share the dictionary.
768 # Required <enums> attributes: 'name', 'value'
770 for enum in self.reg.findall('enums/enum'):
771 self.addElementInfo(enum, EnumInfo(enum), 'enum', self.enumdict)
773 # Create dictionary of registry commands from <command> tags
774 # and add 'name' attribute to each <command> tag (where missing)
775 # based on its <proto><name> element.
777 # There's usually only one <commands> block; more are OK.
778 # Required <command> attributes: 'name' or <proto><name> tag contents
780 for cmd in self.reg.findall('commands/command'):
781 # If the <command> doesn't already have a 'name' attribute, set
782 # it from contents of its <proto><name> tag.
783 if (cmd.get('name') == None):
784 cmd.attrib['name'] = cmd.find('proto/name').text
786 self.addElementInfo(cmd, ci, 'command', self.cmddict)
788 # Create dictionaries of API and extension interfaces
789 # from toplevel <api> and <extension> tags.
792 for feature in self.reg.findall('feature'):
793 ai = FeatureInfo(feature)
794 self.addElementInfo(feature, ai, 'feature', self.apidict)
795 self.extensions = self.reg.findall('extensions/extension')
797 for feature in self.extensions:
798 ei = FeatureInfo(feature)
799 self.addElementInfo(feature, ei, 'extension', self.extdict)
800 def dumpReg(self, maxlen = 40, filehandle = sys.stdout):
801 """Dump all the dictionaries constructed from the Registry object"""
802 write('***************************************', file=filehandle)
803 write(' ** Dumping Registry contents **', file=filehandle)
804 write('***************************************', file=filehandle)
805 write('// Types', file=filehandle)
806 for name in self.typedict:
807 tobj = self.typedict[name]
808 write(' Type', name, '->', etree.tostring(tobj.elem)[0:maxlen], file=filehandle)
809 write('// Groups', file=filehandle)
810 for name in self.groupdict:
811 gobj = self.groupdict[name]
812 write(' Group', name, '->', etree.tostring(gobj.elem)[0:maxlen], file=filehandle)
813 write('// Enums', file=filehandle)
814 for name in self.enumdict:
815 eobj = self.enumdict[name]
816 write(' Enum', name, '->', etree.tostring(eobj.elem)[0:maxlen], file=filehandle)
817 write('// Commands', file=filehandle)
818 for name in self.cmddict:
819 cobj = self.cmddict[name]
820 write(' Command', name, '->', etree.tostring(cobj.elem)[0:maxlen], file=filehandle)
821 write('// APIs', file=filehandle)
822 for key in self.apidict:
823 write(' API Version ', key, '->',
824 etree.tostring(self.apidict[key].elem)[0:maxlen], file=filehandle)
825 write('// Extensions', file=filehandle)
826 for key in self.extdict:
827 write(' Extension', key, '->',
828 etree.tostring(self.extdict[key].elem)[0:maxlen], file=filehandle)
829 # write('***************************************', file=filehandle)
830 # write(' ** Dumping XML ElementTree **', file=filehandle)
831 # write('***************************************', file=filehandle)
832 # write(etree.tostring(self.tree.getroot(),pretty_print=True), file=filehandle)
834 # typename - name of type
835 # required - boolean (to tag features as required or not)
836 def markTypeRequired(self, typename, required):
837 """Require (along with its dependencies) or remove (but not its dependencies) a type"""
838 self.gen.logMsg('diag', '*** tagging type:', typename, '-> required =', required)
839 # Get TypeInfo object for <type> tag corresponding to typename
840 type = self.lookupElementInfo(typename, self.typedict)
842 # Tag required type dependencies as required.
843 # This DOES NOT un-tag dependencies in a <remove> tag.
844 # See comments in markRequired() below for the reason.
845 if (required and ('requires' in type.elem.attrib)):
846 depType = type.elem.get('requires')
847 self.gen.logMsg('diag', '*** Generating dependent type',
848 depType, 'for type', typename)
849 self.markTypeRequired(depType, required)
850 type.required = required
852 self.gen.logMsg('warn', '*** type:', typename , 'IS NOT DEFINED')
854 # features - Element for <require> or <remove> tag
855 # required - boolean (to tag features as required or not)
856 def markRequired(self, features, required):
857 """Require or remove features specified in the Element"""
858 self.gen.logMsg('diag', '*** markRequired (features = <too long to print>, required =', required, ')')
859 # Loop over types, enums, and commands in the tag
860 # @@ It would be possible to respect 'api' and 'profile' attributes
861 # in individual features, but that's not done yet.
862 for typeElem in features.findall('type'):
863 self.markTypeRequired(typeElem.get('name'), required)
864 for enumElem in features.findall('enum'):
865 name = enumElem.get('name')
866 self.gen.logMsg('diag', '*** tagging enum:', name, '-> required =', required)
867 enum = self.lookupElementInfo(name, self.enumdict)
869 enum.required = required
871 self.gen.logMsg('warn', '*** enum:', name , 'IS NOT DEFINED')
872 for cmdElem in features.findall('command'):
873 name = cmdElem.get('name')
874 self.gen.logMsg('diag', '*** tagging command:', name, '-> required =', required)
875 cmd = self.lookupElementInfo(name, self.cmddict)
877 cmd.required = required
878 # Tag all parameter types of this command as required.
879 # This DOES NOT remove types of commands in a <remove>
880 # tag, because many other commands may use the same type.
881 # We could be more clever and reference count types,
882 # instead of using a boolean.
884 # Look for <ptype> in entire <command> tree,
885 # not just immediate children
886 for ptype in cmd.elem.findall('.//ptype'):
887 self.gen.logMsg('diag', '*** markRequired: command implicitly requires dependent type', ptype.text)
888 self.markTypeRequired(ptype.text, required)
890 self.gen.logMsg('warn', '*** command:', name, 'IS NOT DEFINED')
892 # interface - Element for <version> or <extension>, containing
893 # <require> and <remove> tags
894 # api - string specifying API name being generated
895 # profile - string specifying API profile being generated
896 def requireAndRemoveFeatures(self, interface, api, profile):
897 """Process <recquire> and <remove> tags for a <version> or <extension>"""
898 # <require> marks things that are required by this version/profile
899 for feature in interface.findall('require'):
900 if (matchAPIProfile(api, profile, feature)):
901 self.markRequired(feature,True)
902 # <remove> marks things that are removed by this version/profile
903 for feature in interface.findall('remove'):
904 if (matchAPIProfile(api, profile, feature)):
905 self.markRequired(feature,False)
907 # generateFeature - generate a single type / enum / command,
908 # and all its dependencies as needed.
909 # fname - name of feature (<type>/<enum>/<command>
910 # ftype - type of feature, 'type' | 'enum' | 'command'
911 # dictionary - of *Info objects - self.{type|enum|cmd}dict
912 # genProc - bound function pointer for self.gen.gen{Type|Enum|Cmd}
913 def generateFeature(self, fname, ftype, dictionary, genProc):
914 f = self.lookupElementInfo(fname, dictionary)
916 # No such feature. This is an error, but reported earlier
917 self.gen.logMsg('diag', '*** No entry found for feature', fname,
921 # If feature isn't required, or has already been declared, return
923 self.gen.logMsg('diag', '*** Skipping', ftype, fname, '(not required)')
926 self.gen.logMsg('diag', '*** Skipping', ftype, fname, '(already declared)')
929 # Pull in dependent type declaration(s) of the feature.
930 # For types, there may be one in the 'required' attribute of the element
931 # For commands, there may be many in <ptype> tags within the element
932 # For enums, no dependencies are allowed (though perhasps if you
933 # have a uint64 enum, it should require GLuint64)
934 if (ftype == 'type'):
935 if ('requires' in f.elem.attrib):
936 depname = f.elem.get('requires')
937 self.gen.logMsg('diag', '*** Generating required dependent type',
939 self.generateFeature(depname, 'type', self.typedict,
941 elif (ftype == 'command'):
942 for ptype in f.elem.findall('.//ptype'):
944 self.gen.logMsg('diag', '*** Generating required parameter type',
946 self.generateFeature(depname, 'type', self.typedict,
949 # Actually generate the type only if emitting declarations
950 if self.emitFeatures:
951 self.gen.logMsg('diag', '*** Emitting', ftype, 'decl for', fname)
954 self.gen.logMsg('diag', '*** Skipping', ftype, fname,
955 '(not emitting this feature)')
956 # Always mark feature declared, as though actually emitted
959 # generateRequiredInterface - generate all interfaces required
960 # by an API version or extension
961 # interface - Element for <version> or <extension>
962 def generateRequiredInterface(self, interface):
963 """Generate required C interface for specified API version/extension"""
965 # Loop over all features inside all <require> tags.
966 # <remove> tags are ignored (handled in pass 1).
967 for features in interface.findall('require'):
968 for t in features.findall('type'):
969 self.generateFeature(t.get('name'), 'type', self.typedict,
971 for e in features.findall('enum'):
972 self.generateFeature(e.get('name'), 'enum', self.enumdict,
974 for c in features.findall('command'):
975 self.generateFeature(c.get('name'), 'command', self.cmddict,
978 # apiGen(genOpts) - generate interface for specified versions
979 # genOpts - GeneratorOptions object with parameters used
980 # by the Generator object.
981 def apiGen(self, genOpts):
982 """Generate interfaces for the specified API type and range of versions"""
984 self.gen.logMsg('diag', '*******************************************')
985 self.gen.logMsg('diag', ' Registry.apiGen file:', genOpts.filename,
986 'api:', genOpts.apiname,
987 'profile:', genOpts.profile)
988 self.gen.logMsg('diag', '*******************************************')
990 self.genOpts = genOpts
991 # Reset required/declared flags for all features
994 # Compile regexps used to select versions & extensions
995 regVersions = re.compile(self.genOpts.versions)
996 regEmitVersions = re.compile(self.genOpts.emitversions)
997 regAddExtensions = re.compile(self.genOpts.addExtensions)
998 regRemoveExtensions = re.compile(self.genOpts.removeExtensions)
1000 # Get all matching API versions & add to list of FeatureInfo
1003 for key in self.apidict:
1004 fi = self.apidict[key]
1005 api = fi.elem.get('api')
1006 if (api == self.genOpts.apiname):
1008 if (regVersions.match(fi.number)):
1009 # Matches API & version #s being generated. Mark for
1010 # emission and add to the features[] list .
1011 # @@ Could use 'declared' instead of 'emit'?
1012 fi.emit = (regEmitVersions.match(fi.number) != None)
1015 self.gen.logMsg('diag', '*** NOT tagging feature api =', api,
1016 'name =', fi.name, 'number =', fi.number,
1017 'for emission (does not match emitversions pattern)')
1019 self.gen.logMsg('diag', '*** NOT including feature api =', api,
1020 'name =', fi.name, 'number =', fi.number,
1021 '(does not match requested versions)')
1023 self.gen.logMsg('diag', '*** NOT including feature api =', api,
1025 '(does not match requested API)')
1027 self.gen.logMsg('warn', '*** No matching API versions found!')
1029 # Get all matching extensions & add to the list.
1030 # Start with extensions tagged with 'api' pattern matching the API
1031 # being generated. Add extensions matching the pattern specified in
1032 # regExtensions, then remove extensions matching the pattern
1033 # specified in regRemoveExtensions
1034 for key in self.extdict:
1035 ei = self.extdict[key]
1039 # Include extension if defaultExtensions is not None and if the
1040 # 'supported' attribute matches defaultExtensions. The regexp in
1041 # 'supported' must exactly match defaultExtensions, so bracket
1043 pat = '^(' + ei.elem.get('supported') + ')$'
1044 if (self.genOpts.defaultExtensions and
1045 re.match(pat, self.genOpts.defaultExtensions)):
1046 self.gen.logMsg('diag', '*** Including extension',
1047 extName, "(defaultExtensions matches the 'supported' attribute)")
1050 # Include additional extensions if the extension name matches
1051 # the regexp specified in the generator options. This allows
1052 # forcing extensions into an interface even if they're not
1053 # tagged appropriately in the registry.
1054 if (regAddExtensions.match(extName) != None):
1055 self.gen.logMsg('diag', '*** Including extension',
1056 extName, '(matches explicitly requested extensions to add)')
1058 # Remove extensions if the name matches the regexp specified
1059 # in generator options. This allows forcing removal of
1060 # extensions from an interface even if they're tagged that
1061 # way in the registry.
1062 if (regRemoveExtensions.match(extName) != None):
1063 self.gen.logMsg('diag', '*** Removing extension',
1064 extName, '(matches explicitly requested extensions to remove)')
1067 # If the extension is to be included, add it to the
1068 # extension features list.
1073 self.gen.logMsg('diag', '*** NOT including extension',
1074 extName, '(does not match api attribute or explicitly requested extensions)')
1076 # Sort the extension features list, if a sort procedure is defined
1077 if (self.genOpts.sortProcedure):
1078 self.genOpts.sortProcedure(features)
1080 # Pass 1: loop over requested API versions and extensions tagging
1081 # types/commands/features as required (in an <require> block) or no
1082 # longer required (in an <exclude> block). It is possible to remove
1083 # a feature in one version and restore it later by requiring it in
1085 # If a profile other than 'None' is being generated, it must
1086 # match the profile attribute (if any) of the <require> and
1088 self.gen.logMsg('diag', '*** PASS 1: TAG FEATURES ********************************************')
1090 self.gen.logMsg('diag', '*** PASS 1: Tagging required and removed features for',
1092 self.requireAndRemoveFeatures(f.elem, self.genOpts.apiname, self.genOpts.profile)
1094 # Pass 2: loop over specified API versions and extensions printing
1095 # declarations for required things which haven't already been
1097 self.gen.logMsg('diag', '*** PASS 2: GENERATE INTERFACES FOR FEATURES ************************')
1098 self.gen.beginFile(self.genOpts)
1100 self.gen.logMsg('diag', '*** PASS 2: Generating interface for',
1102 emit = self.emitFeatures = f.emit
1104 self.gen.logMsg('diag', '*** PASS 2: NOT declaring feature',
1105 f.elem.get('name'), 'because it is not tagged for emission')
1106 # Generate the interface (or just tag its elements as having been
1107 # emitted, if they haven't been).
1108 self.gen.beginFeature(f.elem, emit)
1109 self.generateRequiredInterface(f.elem)
1110 self.gen.endFeature()
1113 # apiReset - use between apiGen() calls to reset internal state
1116 """Reset type/enum/command dictionaries before generating another API"""
1117 for type in self.typedict:
1118 self.typedict[type].resetState()
1119 for enum in self.enumdict:
1120 self.enumdict[enum].resetState()
1121 for cmd in self.cmddict:
1122 self.cmddict[cmd].resetState()
1123 for cmd in self.apidict:
1124 self.apidict[cmd].resetState()
1126 # validateGroups - check that group= attributes match actual groups
1128 def validateGroups(self):
1129 """Validate group= attributes on <param> and <proto> tags"""
1130 # Keep track of group names not in <group> tags
1132 self.gen.logMsg('diag', '*** VALIDATING GROUP ATTRIBUTES ***')
1133 for cmd in self.reg.findall('commands/command'):
1134 proto = cmd.find('proto')
1135 funcname = cmd.find('proto/name').text
1136 if ('group' in proto.attrib.keys()):
1137 group = proto.get('group')
1138 # self.gen.logMsg('diag', '*** Command ', funcname, ' has return group ', group)
1139 if (group not in self.groupdict.keys()):
1140 # self.gen.logMsg('diag', '*** Command ', funcname, ' has UNKNOWN return group ', group)
1141 if (group not in badGroup.keys()):
1144 badGroup[group] = badGroup[group] + 1
1145 for param in cmd.findall('param'):
1146 pname = param.find('name')
1150 pname = type.get('name')
1151 if ('group' in param.attrib.keys()):
1152 group = param.get('group')
1153 if (group not in self.groupdict.keys()):
1154 # self.gen.logMsg('diag', '*** Command ', funcname, ' param ', pname, ' has UNKNOWN group ', group)
1155 if (group not in badGroup.keys()):
1158 badGroup[group] = badGroup[group] + 1
1159 if (len(badGroup.keys()) > 0):
1160 self.gen.logMsg('diag', '*** SUMMARY OF UNRECOGNIZED GROUPS ***')
1161 for key in sorted(badGroup.keys()):
1162 self.gen.logMsg('diag', ' ', key, ' occurred ', badGroup[key], ' times')