1#!/usr/bin/python -i 2# 3# Copyright (c) 2013-2016 The Khronos Group Inc. 4# 5# Licensed under the Apache License, Version 2.0 (the "License"); 6# you may not use this file except in compliance with the License. 7# You may obtain a copy of the License at 8# 9# http://www.apache.org/licenses/LICENSE-2.0 10# 11# Unless required by applicable law or agreed to in writing, software 12# distributed under the License is distributed on an "AS IS" BASIS, 13# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14# See the License for the specific language governing permissions and 15# limitations under the License. 16 17import io,os,re,string,sys 18from lxml import etree 19import subprocess 20 21def write(*args, **kwargs): 22 file = kwargs.pop('file', sys.stdout) 23 end = kwargs.pop('end', '\n') 24 file.write(' '.join([str(arg) for arg in args])) 25 file.write(end) 26 27# noneStr - returns string argument, or "" if argument is None. 28# Used in converting lxml Elements into text. 29# str - string to convert 30def noneStr(str): 31 if (str): 32 return str 33 else: 34 return "" 35 36# matchAPIProfile - returns whether an API and profile 37# being generated matches an element's profile 38# api - string naming the API to match 39# profile - string naming the profile to match 40# elem - Element which (may) have 'api' and 'profile' 41# attributes to match to. 42# If a tag is not present in the Element, the corresponding API 43# or profile always matches. 44# Otherwise, the tag must exactly match the API or profile. 45# Thus, if 'profile' = core: 46# <remove> with no attribute will match 47# <remove profile='core'> will match 48# <remove profile='compatibility'> will not match 49# Possible match conditions: 50# Requested Element 51# Profile Profile 52# --------- -------- 53# None None Always matches 54# 'string' None Always matches 55# None 'string' Does not match. Can't generate multiple APIs 56# or profiles, so if an API/profile constraint 57# is present, it must be asked for explicitly. 58# 'string' 'string' Strings must match 59# 60# ** In the future, we will allow regexes for the attributes, 61# not just strings, so that api="^(gl|gles2)" will match. Even 62# this isn't really quite enough, we might prefer something 63# like "gl(core)|gles1(common-lite)". 64def matchAPIProfile(api, profile, elem): 65 """Match a requested API & profile name to a api & profile attributes of an Element""" 66 match = True 67 # Match 'api', if present 68 if ('api' in elem.attrib): 69 if (api == None): 70 raise UserWarning("No API requested, but 'api' attribute is present with value '" + 71 elem.get('api') + "'") 72 elif (api != elem.get('api')): 73 # Requested API doesn't match attribute 74 return False 75 if ('profile' in elem.attrib): 76 if (profile == None): 77 raise UserWarning("No profile requested, but 'profile' attribute is present with value '" + 78 elem.get('profile') + "'") 79 elif (profile != elem.get('profile')): 80 # Requested profile doesn't match attribute 81 return False 82 return True 83 84# BaseInfo - base class for information about a registry feature 85# (type/group/enum/command/API/extension). 86# required - should this feature be defined during header generation 87# (has it been removed by a profile or version)? 88# declared - has this feature been defined already? 89# elem - lxml.etree Element for this feature 90# resetState() - reset required/declared to initial values. Used 91# prior to generating a new API interface. 92class BaseInfo: 93 """Represents the state of a registry feature, used during API generation""" 94 def __init__(self, elem): 95 self.required = False 96 self.declared = False 97 self.elem = elem 98 def resetState(self): 99 self.required = False 100 self.declared = False 101 102# TypeInfo - registry information about a type. No additional state 103# beyond BaseInfo is required. 104class TypeInfo(BaseInfo): 105 """Represents the state of a registry type""" 106 def __init__(self, elem): 107 BaseInfo.__init__(self, elem) 108 109# GroupInfo - registry information about a group of related enums. 110# enums - dictionary of enum names which are in the group 111class GroupInfo(BaseInfo): 112 """Represents the state of a registry enumerant group""" 113 def __init__(self, elem): 114 BaseInfo.__init__(self, elem) 115 self.enums = {} 116 117# EnumInfo - registry information about an enum 118# type - numeric type of the value of the <enum> tag 119# ( '' for GLint, 'u' for GLuint, 'ull' for GLuint64 ) 120class EnumInfo(BaseInfo): 121 """Represents the state of a registry enum""" 122 def __init__(self, elem): 123 BaseInfo.__init__(self, elem) 124 self.type = elem.get('type') 125 if (self.type == None): 126 self.type = '' 127 128# CmdInfo - registry information about a command 129# glxtype - type of GLX protocol { None, 'render', 'single', 'vendor' } 130# glxopcode - GLX protocol opcode { None, number } 131# glxequiv - equivalent command at GLX dispatch level { None, string } 132# vecequiv - equivalent vector form of a command taking multiple scalar args 133# { None, string } 134class CmdInfo(BaseInfo): 135 """Represents the state of a registry command""" 136 def __init__(self, elem): 137 BaseInfo.__init__(self, elem) 138 self.glxtype = None 139 self.glxopcode = None 140 self.glxequiv = None 141 self.vecequiv = None 142 143# FeatureInfo - registry information about an API <feature> 144# or <extension> 145# name - feature name string (e.g. 'GL_ARB_multitexture') 146# number - feature version number (e.g. 1.2). <extension> 147# features are unversioned and assigned version number 0. 148# category - category, e.g. VERSION or ARB/KHR/OES/ETC/vendor 149# emit - has this feature been defined already? 150class FeatureInfo(BaseInfo): 151 """Represents the state of an API feature (version/extension)""" 152 def __init__(self, elem): 153 BaseInfo.__init__(self, elem) 154 self.name = elem.get('name') 155 # Determine element category (vendor). Only works 156 # for <extension> elements. 157 if (elem.tag == 'feature'): 158 self.category = 'VERSION' 159 self.number = elem.get('number') 160 else: 161 self.category = self.name.split('_', 2)[1] 162 self.number = "0" 163 self.emit = False 164 165# Primary sort key for regSortFeatures. 166# Sorts by category of the feature name string: 167# Core API features (those defined with a <feature> tag) 168# ARB/KHR/OES (Khronos extensions) 169# other (EXT/vendor extensions) 170def regSortCategoryKey(feature): 171 if (feature.elem.tag == 'feature'): 172 return 0 173 elif (feature.category == 'ARB' or 174 feature.category == 'KHR' or 175 feature.category == 'OES'): 176 return 1 177 else: 178 return 2 179 180# Secondary sort key for regSortFeatures. 181# Sorts by extension name. 182def regSortNameKey(feature): 183 return feature.name 184 185# Tertiary sort key for regSortFeatures. 186# Sorts by feature version number. <extension> 187# elements all have version number "0" 188def regSortNumberKey(feature): 189 return feature.number 190 191# regSortFeatures - default sort procedure for features. 192# Sorts by primary key of feature category, 193# then by feature name within the category, 194# then by version number 195def regSortFeatures(featureList): 196 featureList.sort(key = regSortNumberKey) 197 featureList.sort(key = regSortNameKey) 198 featureList.sort(key = regSortCategoryKey) 199 200# GeneratorOptions - base class for options used during header production 201# These options are target language independent, and used by 202# Registry.apiGen() and by base OutputGenerator objects. 203# 204# Members 205# filename - name of file to generate, or None to write to stdout. 206# apiname - string matching <api> 'apiname' attribute, e.g. 'gl'. 207# profile - string specifying API profile , e.g. 'core', or None. 208# versions - regex matching API versions to process interfaces for. 209# Normally '.*' or '[0-9]\.[0-9]' to match all defined versions. 210# emitversions - regex matching API versions to actually emit 211# interfaces for (though all requested versions are considered 212# when deciding which interfaces to generate). For GL 4.3 glext.h, 213# this might be '1\.[2-5]|[2-4]\.[0-9]'. 214# defaultExtensions - If not None, a string which must in its 215# entirety match the pattern in the "supported" attribute of 216# the <extension>. Defaults to None. Usually the same as apiname. 217# addExtensions - regex matching names of additional extensions 218# to include. Defaults to None. 219# removeExtensions - regex matching names of extensions to 220# remove (after defaultExtensions and addExtensions). Defaults 221# to None. 222# sortProcedure - takes a list of FeatureInfo objects and sorts 223# them in place to a preferred order in the generated output. 224# Default is core API versions, ARB/KHR/OES extensions, all 225# other extensions, alphabetically within each group. 226# The regex patterns can be None or empty, in which case they match 227# nothing. 228class GeneratorOptions: 229 """Represents options during header production from an API registry""" 230 def __init__(self, 231 filename = None, 232 apiname = None, 233 profile = None, 234 versions = '.*', 235 emitversions = '.*', 236 defaultExtensions = None, 237 addExtensions = None, 238 removeExtensions = None, 239 sortProcedure = regSortFeatures): 240 self.filename = filename 241 self.apiname = apiname 242 self.profile = profile 243 self.versions = self.emptyRegex(versions) 244 self.emitversions = self.emptyRegex(emitversions) 245 self.defaultExtensions = defaultExtensions 246 self.addExtensions = self.emptyRegex(addExtensions) 247 self.removeExtensions = self.emptyRegex(removeExtensions) 248 self.sortProcedure = sortProcedure 249 # 250 # Substitute a regular expression which matches no version 251 # or extension names for None or the empty string. 252 def emptyRegex(self,pat): 253 if (pat == None or pat == ''): 254 return '_nomatch_^' 255 else: 256 return pat 257 258# CGeneratorOptions - subclass of GeneratorOptions. 259# 260# Adds options used by COutputGenerator objects during C language header 261# generation. 262# 263# Additional members 264# prefixText - list of strings to prefix generated header with 265# (usually a copyright statement + calling convention macros). 266# protectFile - True if multiple inclusion protection should be 267# generated (based on the filename) around the entire header. 268# protectFeature - True if #ifndef..#endif protection should be 269# generated around a feature interface in the header file. 270# genFuncPointers - True if function pointer typedefs should be 271# generated 272# protectProto - Controls cpp protection around prototypes: 273# False - no protection 274# 'nonzero' - protectProtoStr must be defined to a nonzero value 275# True - protectProtoStr must be defined 276# protectProtoStr - #ifdef symbol to use around prototype 277# declarations, if protected 278# apicall - string to use for the function declaration prefix, 279# such as APICALL on Windows. 280# apientry - string to use for the calling convention macro, 281# in typedefs, such as APIENTRY. 282# apientryp - string to use for the calling convention macro 283# in function pointer typedefs, such as APIENTRYP. 284class CGeneratorOptions(GeneratorOptions): 285 """Represents options during C header production from an API registry""" 286 def __init__(self, 287 filename = None, 288 apiname = None, 289 profile = None, 290 versions = '.*', 291 emitversions = '.*', 292 defaultExtensions = None, 293 addExtensions = None, 294 removeExtensions = None, 295 sortProcedure = regSortFeatures, 296 prefixText = "", 297 genFuncPointers = True, 298 protectFile = True, 299 protectFeature = True, 300 protectProto = True, 301 protectProtoStr = True, 302 apicall = '', 303 apientry = '', 304 apientryp = ''): 305 GeneratorOptions.__init__(self, filename, apiname, profile, 306 versions, emitversions, defaultExtensions, 307 addExtensions, removeExtensions, sortProcedure) 308 self.prefixText = prefixText 309 self.genFuncPointers = genFuncPointers 310 self.protectFile = protectFile 311 self.protectFeature = protectFeature 312 self.protectProto = protectProto 313 self.protectProtoStr = protectProtoStr 314 self.apicall = apicall 315 self.apientry = apientry 316 self.apientryp = apientryp 317 318# OutputGenerator - base class for generating API interfaces. 319# Manages basic logic, logging, and output file control 320# Derived classes actually generate formatted output. 321# 322# ---- methods ---- 323# OutputGenerator(errFile, warnFile, diagFile) 324# errFile, warnFile, diagFile - file handles to write errors, 325# warnings, diagnostics to. May be None to not write. 326# logMsg(level, *args) - log messages of different categories 327# level - 'error', 'warn', or 'diag'. 'error' will also 328# raise a UserWarning exception 329# *args - print()-style arguments 330# beginFile(genOpts) - start a new interface file 331# genOpts - GeneratorOptions controlling what's generated and how 332# endFile() - finish an interface file, closing it when done 333# beginFeature(interface, emit) - write interface for a feature 334# and tag generated features as having been done. 335# interface - element for the <version> / <extension> to generate 336# emit - actually write to the header only when True 337# endFeature() - finish an interface. 338# genType(typeinfo,name) - generate interface for a type 339# typeinfo - TypeInfo for a type 340# genEnum(enuminfo, name) - generate interface for an enum 341# enuminfo - EnumInfo for an enum 342# name - enum name 343# genCmd(cmdinfo) - generate interface for a command 344# cmdinfo - CmdInfo for a command 345class OutputGenerator: 346 """Generate specified API interfaces in a specific style, such as a C header""" 347 def __init__(self, 348 errFile = sys.stderr, 349 warnFile = sys.stderr, 350 diagFile = sys.stdout): 351 self.outFile = None 352 self.errFile = errFile 353 self.warnFile = warnFile 354 self.diagFile = diagFile 355 # Internal state 356 self.featureName = None 357 self.genOpts = None 358 # 359 # logMsg - write a message of different categories to different 360 # destinations. 361 # level - 362 # 'diag' (diagnostic, voluminous) 363 # 'warn' (warning) 364 # 'error' (fatal error - raises exception after logging) 365 # *args - print()-style arguments to direct to corresponding log 366 def logMsg(self, level, *args): 367 """Log a message at the given level. Can be ignored or log to a file""" 368 if (level == 'error'): 369 strfile = io.StringIO() 370 write('ERROR:', *args, file=strfile) 371 if (self.errFile != None): 372 write(strfile.getvalue(), file=self.errFile) 373 raise UserWarning(strfile.getvalue()) 374 elif (level == 'warn'): 375 if (self.warnFile != None): 376 write('WARNING:', *args, file=self.warnFile) 377 elif (level == 'diag'): 378 if (self.diagFile != None): 379 write('DIAG:', *args, file=self.diagFile) 380 else: 381 raise UserWarning( 382 '*** FATAL ERROR in Generator.logMsg: unknown level:' + level) 383 # 384 def beginFile(self, genOpts): 385 self.genOpts = genOpts 386 # 387 # Open specified output file. Not done in constructor since a 388 # Generator can be used without writing to a file. 389 if (self.genOpts.filename != None): 390 self.outFile = open(self.genOpts.filename, 'w') 391 else: 392 self.outFile = sys.stdout 393 def endFile(self): 394 self.errFile and self.errFile.flush() 395 self.warnFile and self.warnFile.flush() 396 self.diagFile and self.diagFile.flush() 397 self.outFile.flush() 398 if (self.outFile != sys.stdout and self.outFile != sys.stderr): 399 self.outFile.close() 400 self.genOpts = None 401 # 402 def beginFeature(self, interface, emit): 403 self.emit = emit 404 self.featureName = interface.get('name') 405 # If there's an additional 'protect' attribute in the feature, save it 406 self.featureExtraProtect = interface.get('protect') 407 def endFeature(self): 408 # Derived classes responsible for emitting feature 409 self.featureName = None 410 self.featureExtraProtect = None 411 # 412 # Type generation 413 def genType(self, typeinfo, name): 414 if (self.featureName == None): 415 raise UserWarning('Attempt to generate type', name, 416 'when not in feature') 417 # 418 # Enumerant generation 419 def genEnum(self, enuminfo, name): 420 if (self.featureName == None): 421 raise UserWarning('Attempt to generate enum', name, 422 'when not in feature') 423 # 424 # Command generation 425 def genCmd(self, cmd, name): 426 if (self.featureName == None): 427 raise UserWarning('Attempt to generate command', name, 428 'when not in feature') 429 430# COutputGenerator - subclass of OutputGenerator. 431# Generates C-language API interfaces. 432# 433# ---- methods ---- 434# COutputGenerator(errFile, warnFile, diagFile) - args as for 435# OutputGenerator. Defines additional internal state. 436# makeCDecls(cmd) - return C prototype and function pointer typedef for a 437# <command> Element, as a list of two strings 438# cmd - Element for the <command> 439# newline() - print a newline to the output file (utility function) 440# ---- methods overriding base class ---- 441# beginFile(genOpts) 442# endFile() 443# beginFeature(interface, emit) 444# endFeature() 445# genType(typeinfo,name) - generate interface for a type 446# genEnum(enuminfo, name) 447# genCmd(cmdinfo) 448class COutputGenerator(OutputGenerator): 449 """Generate specified API interfaces in a specific style, such as a C header""" 450 def __init__(self, 451 errFile = sys.stderr, 452 warnFile = sys.stderr, 453 diagFile = sys.stdout): 454 OutputGenerator.__init__(self, errFile, warnFile, diagFile) 455 # Internal state - accumulators for different inner block text 456 self.typeBody = '' 457 self.enumBody = '' 458 self.cmdBody = '' 459 # 460 # makeCDecls - return C prototype and function pointer typedef for a 461 # command, as a two-element list of strings. 462 # cmd - Element containing a <command> tag 463 def makeCDecls(self, cmd): 464 """Generate C function pointer typedef for <command> Element""" 465 proto = cmd.find('proto') 466 params = cmd.findall('param') 467 # Begin accumulating prototype and typedef strings 468 pdecl = self.genOpts.apicall 469 tdecl = 'typedef ' 470 # 471 # Insert the function return type/name. 472 # For prototypes, add APIENTRY macro before the name 473 # For typedefs, add (APIENTRYP <name>) around the name and 474 # use the PFNGLCMDNAMEPROC nameng convention. 475 # Done by walking the tree for <proto> element by element. 476 # lxml.etree has elem.text followed by (elem[i], elem[i].tail) 477 # for each child element and any following text 478 # Leading text 479 pdecl += noneStr(proto.text) 480 tdecl += noneStr(proto.text) 481 # For each child element, if it's a <name> wrap in appropriate 482 # declaration. Otherwise append its contents and tail contents. 483 for elem in proto: 484 text = noneStr(elem.text) 485 tail = noneStr(elem.tail) 486 if (elem.tag == 'name'): 487 pdecl += self.genOpts.apientry + text + tail 488 tdecl += '(' + self.genOpts.apientryp + 'PFN' + text.upper() + 'PROC' + tail + ')' 489 else: 490 pdecl += text + tail 491 tdecl += text + tail 492 # Now add the parameter declaration list, which is identical 493 # for prototypes and typedefs. Concatenate all the text from 494 # a <param> node without the tags. No tree walking required 495 # since all tags are ignored. 496 n = len(params) 497 paramdecl = ' (' 498 if n > 0: 499 for i in range(0,n): 500 paramdecl += ''.join([t for t in params[i].itertext()]) 501 if (i < n - 1): 502 paramdecl += ', ' 503 else: 504 paramdecl += 'void' 505 paramdecl += ');\n'; 506 return [ pdecl + paramdecl, tdecl + paramdecl ] 507 # 508 def newline(self): 509 write('', file=self.outFile) 510 # 511 def beginFile(self, genOpts): 512 OutputGenerator.beginFile(self, genOpts) 513 # C-specific 514 # 515 # Multiple inclusion protection & C++ wrappers. 516 if (genOpts.protectFile and self.genOpts.filename): 517 headerSym = '__' + re.sub('\.h', '_h_', os.path.basename(self.genOpts.filename)) 518 write('#ifndef', headerSym, file=self.outFile) 519 write('#define', headerSym, '1', file=self.outFile) 520 self.newline() 521 write('#ifdef __cplusplus', file=self.outFile) 522 write('extern "C" {', file=self.outFile) 523 write('#endif', file=self.outFile) 524 self.newline() 525 # 526 # User-supplied prefix text, if any (list of strings) 527 if (genOpts.prefixText): 528 try: 529 git_rev = subprocess.check_output(['git', 'rev-parse', '--short=10', 'HEAD']).decode('utf-8').strip() 530 git_date = subprocess.check_output(['git', 'log', '-1', '--format=%ai']).decode('utf-8').strip() 531 except (OSError, subprocess.CalledProcessError): 532 git_rev = 'unknown' 533 git_date = 'unknown' 534 for s in genOpts.prefixText: 535 s = s.replace('$Revision$', '$Git commit SHA1: ' + git_rev + ' $') 536 s = s.replace('$Date$', '$Git commit date: ' + git_date + ' $') 537 write(s, file=self.outFile) 538 # 539 # Some boilerplate describing what was generated - this 540 # will probably be removed later since the extensions 541 # pattern may be very long. 542 write('/* Generated C header for:', file=self.outFile) 543 write(' * API:', genOpts.apiname, file=self.outFile) 544 if (genOpts.profile): 545 write(' * Profile:', genOpts.profile, file=self.outFile) 546 write(' * Versions considered:', genOpts.versions, file=self.outFile) 547 write(' * Versions emitted:', genOpts.emitversions, file=self.outFile) 548 write(' * Default extensions included:', genOpts.defaultExtensions, file=self.outFile) 549 write(' * Additional extensions included:', genOpts.addExtensions, file=self.outFile) 550 write(' * Extensions removed:', genOpts.removeExtensions, file=self.outFile) 551 write(' */', file=self.outFile) 552 def endFile(self): 553 # C-specific 554 # Finish C++ wrapper and multiple inclusion protection 555 self.newline() 556 write('#ifdef __cplusplus', file=self.outFile) 557 write('}', file=self.outFile) 558 write('#endif', file=self.outFile) 559 if (self.genOpts.protectFile and self.genOpts.filename): 560 self.newline() 561 write('#endif', file=self.outFile) 562 # Finish processing in superclass 563 OutputGenerator.endFile(self) 564 def beginFeature(self, interface, emit): 565 # Start processing in superclass 566 OutputGenerator.beginFeature(self, interface, emit) 567 # C-specific 568 # Accumulate types, enums, function pointer typedefs, end function 569 # prototypes separately for this feature. They're only printed in 570 # endFeature(). 571 self.typeBody = '' 572 self.enumBody = '' 573 self.cmdPointerBody = '' 574 self.cmdBody = '' 575 def endFeature(self): 576 # C-specific 577 # Actually write the interface to the output file. 578 if (self.emit): 579 self.newline() 580 if (self.genOpts.protectFeature): 581 write('#ifndef', self.featureName, file=self.outFile) 582 write('#define', self.featureName, '1', file=self.outFile) 583 if (self.typeBody != ''): 584 write(self.typeBody, end='', file=self.outFile) 585 # 586 # Don't add additional protection for derived type declarations, 587 # which may be needed by other features later on. 588 if (self.featureExtraProtect != None): 589 write('#ifdef', self.featureExtraProtect, file=self.outFile) 590 if (self.enumBody != ''): 591 write(self.enumBody, end='', file=self.outFile) 592 if (self.genOpts.genFuncPointers and self.cmdPointerBody != ''): 593 write(self.cmdPointerBody, end='', file=self.outFile) 594 if (self.cmdBody != ''): 595 if (self.genOpts.protectProto == True): 596 prefix = '#ifdef ' + self.genOpts.protectProtoStr + '\n' 597 suffix = '#endif\n' 598 elif (self.genOpts.protectProto == 'nonzero'): 599 prefix = '#if ' + self.genOpts.protectProtoStr + '\n' 600 suffix = '#endif\n' 601 elif (self.genOpts.protectProto == False): 602 prefix = '' 603 suffix = '' 604 else: 605 self.gen.logMsg('warn', 606 '*** Unrecognized value for protectProto:', 607 self.genOpts.protectProto, 608 'not generating prototype wrappers') 609 prefix = '' 610 suffix = '' 611 612 write(prefix + self.cmdBody + suffix, end='', file=self.outFile) 613 if (self.featureExtraProtect != None): 614 write('#endif /*', self.featureExtraProtect, '*/', file=self.outFile) 615 if (self.genOpts.protectFeature): 616 write('#endif /*', self.featureName, '*/', file=self.outFile) 617 # Finish processing in superclass 618 OutputGenerator.endFeature(self) 619 # 620 # Type generation 621 def genType(self, typeinfo, name): 622 OutputGenerator.genType(self, typeinfo, name) 623 # 624 # Replace <apientry /> tags with an APIENTRY-style string 625 # (from self.genOpts). Copy other text through unchanged. 626 # If the resulting text is an empty string, don't emit it. 627 typeElem = typeinfo.elem 628 s = noneStr(typeElem.text) 629 for elem in typeElem: 630 if (elem.tag == 'apientry'): 631 s += self.genOpts.apientry + noneStr(elem.tail) 632 else: 633 s += noneStr(elem.text) + noneStr(elem.tail) 634 if (len(s) > 0): 635 self.typeBody += s + '\n' 636 # 637 # Enumerant generation 638 def genEnum(self, enuminfo, name): 639 OutputGenerator.genEnum(self, enuminfo, name) 640 # 641 # EnumInfo.type is a C value suffix (e.g. u, ull) 642 self.enumBody += '#define ' + name.ljust(33) + ' ' + enuminfo.elem.get('value') 643 # 644 # Handle non-integer 'type' fields by using it as the C value suffix 645 t = enuminfo.elem.get('type') 646 if (t != '' and t != 'i'): 647 self.enumBody += enuminfo.type 648 self.enumBody += '\n' 649 # 650 # Command generation 651 def genCmd(self, cmdinfo, name): 652 OutputGenerator.genCmd(self, cmdinfo, name) 653 # 654 decls = self.makeCDecls(cmdinfo.elem) 655 self.cmdBody += decls[0] 656 if (self.genOpts.genFuncPointers): 657 self.cmdPointerBody += decls[1] 658 659# Registry - object representing an API registry, loaded from an XML file 660# Members 661# tree - ElementTree containing the root <registry> 662# typedict - dictionary of TypeInfo objects keyed by type name 663# groupdict - dictionary of GroupInfo objects keyed by group name 664# enumdict - dictionary of EnumInfo objects keyed by enum name 665# cmddict - dictionary of CmdInfo objects keyed by command name 666# apidict - dictionary of <api> Elements keyed by API name 667# extensions - list of <extension> Elements 668# extdict - dictionary of <extension> Elements keyed by extension name 669# gen - OutputGenerator object used to write headers / messages 670# genOpts - GeneratorOptions object used to control which 671# fetures to write and how to format them 672# emitFeatures - True to actually emit features for a version / extension, 673# or False to just treat them as emitted 674# Public methods 675# loadElementTree(etree) - load registry from specified ElementTree 676# loadFile(filename) - load registry from XML file 677# setGenerator(gen) - OutputGenerator to use 678# parseTree() - parse the registry once loaded & create dictionaries 679# dumpReg(maxlen, filehandle) - diagnostic to dump the dictionaries 680# to specified file handle (default stdout). Truncates type / 681# enum / command elements to maxlen characters (default 80) 682# generator(g) - specify the output generator object 683# apiGen(apiname, genOpts) - generate API headers for the API type 684# and profile specified in genOpts, but only for the versions and 685# extensions specified there. 686# apiReset() - call between calls to apiGen() to reset internal state 687# validateGroups() - call to verify that each <proto> or <param> 688# with a 'group' attribute matches an actual existing group. 689# Private methods 690# addElementInfo(elem,info,infoName,dictionary) - add feature info to dict 691# lookupElementInfo(fname,dictionary) - lookup feature info in dict 692class Registry: 693 """Represents an API registry loaded from XML""" 694 def __init__(self): 695 self.tree = None 696 self.typedict = {} 697 self.groupdict = {} 698 self.enumdict = {} 699 self.cmddict = {} 700 self.apidict = {} 701 self.extensions = [] 702 self.extdict = {} 703 # A default output generator, so commands prior to apiGen can report 704 # errors via the generator object. 705 self.gen = OutputGenerator() 706 self.genOpts = None 707 self.emitFeatures = False 708 def loadElementTree(self, tree): 709 """Load ElementTree into a Registry object and parse it""" 710 self.tree = tree 711 self.parseTree() 712 def loadFile(self, file): 713 """Load an API registry XML file into a Registry object and parse it""" 714 self.tree = etree.parse(file) 715 self.parseTree() 716 def setGenerator(self, gen): 717 """Specify output generator object. None restores the default generator""" 718 self.gen = gen 719 # addElementInfo - add information about an element to the 720 # corresponding dictionary 721 # elem - <type>/<group>/<enum>/<command>/<feature>/<extension> Element 722 # info - corresponding {Type|Group|Enum|Cmd|Feature}Info object 723 # infoName - 'type' / 'group' / 'enum' / 'command' / 'feature' / 'extension' 724 # dictionary - self.{type|group|enum|cmd|api|ext}dict 725 # If the Element has an 'api' attribute, the dictionary key is the 726 # tuple (name,api). If not, the key is the name. 'name' is an 727 # attribute of the Element 728 def addElementInfo(self, elem, info, infoName, dictionary): 729 if ('api' in elem.attrib): 730 key = (elem.get('name'),elem.get('api')) 731 else: 732 key = elem.get('name') 733 if key in dictionary: 734 self.gen.logMsg('warn', '*** Attempt to redefine', 735 infoName, 'with key:', key) 736 else: 737 dictionary[key] = info 738 # 739 # lookupElementInfo - find a {Type|Enum|Cmd}Info object by name. 740 # If an object qualified by API name exists, use that. 741 # fname - name of type / enum / command 742 # dictionary - self.{type|enum|cmd}dict 743 def lookupElementInfo(self, fname, dictionary): 744 key = (fname, self.genOpts.apiname) 745 if (key in dictionary): 746 # self.gen.logMsg('diag', 'Found API-specific element for feature', fname) 747 return dictionary[key] 748 elif (fname in dictionary): 749 # self.gen.logMsg('diag', 'Found generic element for feature', fname) 750 return dictionary[fname] 751 else: 752 return None 753 def parseTree(self): 754 """Parse the registry Element, once created""" 755 # This must be the Element for the root <registry> 756 self.reg = self.tree.getroot() 757 # 758 # Create dictionary of registry types from toplevel <types> tags 759 # and add 'name' attribute to each <type> tag (where missing) 760 # based on its <name> element. 761 # 762 # There's usually one <types> block; more are OK 763 # Required <type> attributes: 'name' or nested <name> tag contents 764 self.typedict = {} 765 for type in self.reg.findall('types/type'): 766 # If the <type> doesn't already have a 'name' attribute, set 767 # it from contents of its <name> tag. 768 if (type.get('name') == None): 769 type.attrib['name'] = type.find('name').text 770 self.addElementInfo(type, TypeInfo(type), 'type', self.typedict) 771 # 772 # Create dictionary of registry groups from toplevel <groups> tags. 773 # 774 # There's usually one <groups> block; more are OK. 775 # Required <group> attributes: 'name' 776 self.groupdict = {} 777 for group in self.reg.findall('groups/group'): 778 self.addElementInfo(group, GroupInfo(group), 'group', self.groupdict) 779 # 780 # Create dictionary of registry enums from toplevel <enums> tags 781 # 782 # There are usually many <enums> tags in different namespaces, but 783 # these are functional namespaces of the values, while the actual 784 # enum names all share the dictionary. 785 # Required <enums> attributes: 'name', 'value' 786 self.enumdict = {} 787 for enum in self.reg.findall('enums/enum'): 788 self.addElementInfo(enum, EnumInfo(enum), 'enum', self.enumdict) 789 # 790 # Create dictionary of registry commands from <command> tags 791 # and add 'name' attribute to each <command> tag (where missing) 792 # based on its <proto><name> element. 793 # 794 # There's usually only one <commands> block; more are OK. 795 # Required <command> attributes: 'name' or <proto><name> tag contents 796 self.cmddict = {} 797 for cmd in self.reg.findall('commands/command'): 798 # If the <command> doesn't already have a 'name' attribute, set 799 # it from contents of its <proto><name> tag. 800 if (cmd.get('name') == None): 801 cmd.attrib['name'] = cmd.find('proto/name').text 802 ci = CmdInfo(cmd) 803 self.addElementInfo(cmd, ci, 'command', self.cmddict) 804 # 805 # Create dictionaries of API and extension interfaces 806 # from toplevel <api> and <extension> tags. 807 # 808 self.apidict = {} 809 for feature in self.reg.findall('feature'): 810 ai = FeatureInfo(feature) 811 self.addElementInfo(feature, ai, 'feature', self.apidict) 812 self.extensions = self.reg.findall('extensions/extension') 813 self.extdict = {} 814 for feature in self.extensions: 815 ei = FeatureInfo(feature) 816 self.addElementInfo(feature, ei, 'extension', self.extdict) 817 def dumpReg(self, maxlen = 40, filehandle = sys.stdout): 818 """Dump all the dictionaries constructed from the Registry object""" 819 write('***************************************', file=filehandle) 820 write(' ** Dumping Registry contents **', file=filehandle) 821 write('***************************************', file=filehandle) 822 write('// Types', file=filehandle) 823 for name in self.typedict: 824 tobj = self.typedict[name] 825 write(' Type', name, '->', etree.tostring(tobj.elem)[0:maxlen], file=filehandle) 826 write('// Groups', file=filehandle) 827 for name in self.groupdict: 828 gobj = self.groupdict[name] 829 write(' Group', name, '->', etree.tostring(gobj.elem)[0:maxlen], file=filehandle) 830 write('// Enums', file=filehandle) 831 for name in self.enumdict: 832 eobj = self.enumdict[name] 833 write(' Enum', name, '->', etree.tostring(eobj.elem)[0:maxlen], file=filehandle) 834 write('// Commands', file=filehandle) 835 for name in self.cmddict: 836 cobj = self.cmddict[name] 837 write(' Command', name, '->', etree.tostring(cobj.elem)[0:maxlen], file=filehandle) 838 write('// APIs', file=filehandle) 839 for key in self.apidict: 840 write(' API Version ', key, '->', 841 etree.tostring(self.apidict[key].elem)[0:maxlen], file=filehandle) 842 write('// Extensions', file=filehandle) 843 for key in self.extdict: 844 write(' Extension', key, '->', 845 etree.tostring(self.extdict[key].elem)[0:maxlen], file=filehandle) 846 # write('***************************************', file=filehandle) 847 # write(' ** Dumping XML ElementTree **', file=filehandle) 848 # write('***************************************', file=filehandle) 849 # write(etree.tostring(self.tree.getroot(),pretty_print=True), file=filehandle) 850 # 851 # typename - name of type 852 # required - boolean (to tag features as required or not) 853 def markTypeRequired(self, typename, required): 854 """Require (along with its dependencies) or remove (but not its dependencies) a type""" 855 self.gen.logMsg('diag', '*** tagging type:', typename, '-> required =', required) 856 # Get TypeInfo object for <type> tag corresponding to typename 857 type = self.lookupElementInfo(typename, self.typedict) 858 if (type != None): 859 # Tag required type dependencies as required. 860 # This DOES NOT un-tag dependencies in a <remove> tag. 861 # See comments in markRequired() below for the reason. 862 if (required and ('requires' in type.elem.attrib)): 863 depType = type.elem.get('requires') 864 self.gen.logMsg('diag', '*** Generating dependent type', 865 depType, 'for type', typename) 866 self.markTypeRequired(depType, required) 867 type.required = required 868 else: 869 self.gen.logMsg('warn', '*** type:', typename , 'IS NOT DEFINED') 870 # 871 # features - Element for <require> or <remove> tag 872 # required - boolean (to tag features as required or not) 873 def markRequired(self, features, required): 874 """Require or remove features specified in the Element""" 875 self.gen.logMsg('diag', '*** markRequired (features = <too long to print>, required =', required, ')') 876 # Loop over types, enums, and commands in the tag 877 # @@ It would be possible to respect 'api' and 'profile' attributes 878 # in individual features, but that's not done yet. 879 for typeElem in features.findall('type'): 880 self.markTypeRequired(typeElem.get('name'), required) 881 for enumElem in features.findall('enum'): 882 name = enumElem.get('name') 883 self.gen.logMsg('diag', '*** tagging enum:', name, '-> required =', required) 884 enum = self.lookupElementInfo(name, self.enumdict) 885 if (enum != None): 886 enum.required = required 887 else: 888 self.gen.logMsg('warn', '*** enum:', name , 'IS NOT DEFINED') 889 for cmdElem in features.findall('command'): 890 name = cmdElem.get('name') 891 self.gen.logMsg('diag', '*** tagging command:', name, '-> required =', required) 892 cmd = self.lookupElementInfo(name, self.cmddict) 893 if (cmd != None): 894 cmd.required = required 895 # Tag all parameter types of this command as required. 896 # This DOES NOT remove types of commands in a <remove> 897 # tag, because many other commands may use the same type. 898 # We could be more clever and reference count types, 899 # instead of using a boolean. 900 if (required): 901 # Look for <ptype> in entire <command> tree, 902 # not just immediate children 903 for ptype in cmd.elem.findall('.//ptype'): 904 self.gen.logMsg('diag', '*** markRequired: command implicitly requires dependent type', ptype.text) 905 self.markTypeRequired(ptype.text, required) 906 else: 907 self.gen.logMsg('warn', '*** command:', name, 'IS NOT DEFINED') 908 # 909 # interface - Element for <version> or <extension>, containing 910 # <require> and <remove> tags 911 # api - string specifying API name being generated 912 # profile - string specifying API profile being generated 913 def requireAndRemoveFeatures(self, interface, api, profile): 914 """Process <recquire> and <remove> tags for a <version> or <extension>""" 915 # <require> marks things that are required by this version/profile 916 for feature in interface.findall('require'): 917 if (matchAPIProfile(api, profile, feature)): 918 self.markRequired(feature,True) 919 # <remove> marks things that are removed by this version/profile 920 for feature in interface.findall('remove'): 921 if (matchAPIProfile(api, profile, feature)): 922 self.markRequired(feature,False) 923 # 924 # generateFeature - generate a single type / enum / command, 925 # and all its dependencies as needed. 926 # fname - name of feature (<type>/<enum>/<command> 927 # ftype - type of feature, 'type' | 'enum' | 'command' 928 # dictionary - of *Info objects - self.{type|enum|cmd}dict 929 # genProc - bound function pointer for self.gen.gen{Type|Enum|Cmd} 930 def generateFeature(self, fname, ftype, dictionary, genProc): 931 f = self.lookupElementInfo(fname, dictionary) 932 if (f == None): 933 # No such feature. This is an error, but reported earlier 934 self.gen.logMsg('diag', '*** No entry found for feature', fname, 935 'returning!') 936 return 937 # 938 # If feature isn't required, or has already been declared, return 939 if (not f.required): 940 self.gen.logMsg('diag', '*** Skipping', ftype, fname, '(not required)') 941 return 942 if (f.declared): 943 self.gen.logMsg('diag', '*** Skipping', ftype, fname, '(already declared)') 944 return 945 # 946 # Pull in dependent type declaration(s) of the feature. 947 # For types, there may be one in the 'required' attribute of the element 948 # For commands, there may be many in <ptype> tags within the element 949 # For enums, no dependencies are allowed (though perhasps if you 950 # have a uint64 enum, it should require GLuint64) 951 if (ftype == 'type'): 952 if ('requires' in f.elem.attrib): 953 depname = f.elem.get('requires') 954 self.gen.logMsg('diag', '*** Generating required dependent type', 955 depname) 956 self.generateFeature(depname, 'type', self.typedict, 957 self.gen.genType) 958 elif (ftype == 'command'): 959 for ptype in f.elem.findall('.//ptype'): 960 depname = ptype.text 961 self.gen.logMsg('diag', '*** Generating required parameter type', 962 depname) 963 self.generateFeature(depname, 'type', self.typedict, 964 self.gen.genType) 965 # 966 # Actually generate the type only if emitting declarations 967 if self.emitFeatures: 968 self.gen.logMsg('diag', '*** Emitting', ftype, 'decl for', fname) 969 genProc(f, fname) 970 else: 971 self.gen.logMsg('diag', '*** Skipping', ftype, fname, 972 '(not emitting this feature)') 973 # Always mark feature declared, as though actually emitted 974 f.declared = True 975 # 976 # generateRequiredInterface - generate all interfaces required 977 # by an API version or extension 978 # interface - Element for <version> or <extension> 979 def generateRequiredInterface(self, interface): 980 """Generate required C interface for specified API version/extension""" 981 # 982 # Loop over all features inside all <require> tags. 983 # <remove> tags are ignored (handled in pass 1). 984 for features in interface.findall('require'): 985 for t in features.findall('type'): 986 self.generateFeature(t.get('name'), 'type', self.typedict, 987 self.gen.genType) 988 for e in features.findall('enum'): 989 self.generateFeature(e.get('name'), 'enum', self.enumdict, 990 self.gen.genEnum) 991 for c in features.findall('command'): 992 self.generateFeature(c.get('name'), 'command', self.cmddict, 993 self.gen.genCmd) 994 # 995 # apiGen(genOpts) - generate interface for specified versions 996 # genOpts - GeneratorOptions object with parameters used 997 # by the Generator object. 998 def apiGen(self, genOpts): 999 """Generate interfaces for the specified API type and range of versions""" 1000 # 1001 self.gen.logMsg('diag', '*******************************************') 1002 self.gen.logMsg('diag', ' Registry.apiGen file:', genOpts.filename, 1003 'api:', genOpts.apiname, 1004 'profile:', genOpts.profile) 1005 self.gen.logMsg('diag', '*******************************************') 1006 # 1007 self.genOpts = genOpts 1008 # Reset required/declared flags for all features 1009 self.apiReset() 1010 # 1011 # Compile regexps used to select versions & extensions 1012 regVersions = re.compile(self.genOpts.versions) 1013 regEmitVersions = re.compile(self.genOpts.emitversions) 1014 regAddExtensions = re.compile(self.genOpts.addExtensions) 1015 regRemoveExtensions = re.compile(self.genOpts.removeExtensions) 1016 # 1017 # Get all matching API versions & add to list of FeatureInfo 1018 features = [] 1019 apiMatch = False 1020 for key in self.apidict: 1021 fi = self.apidict[key] 1022 api = fi.elem.get('api') 1023 if (api == self.genOpts.apiname): 1024 apiMatch = True 1025 if (regVersions.match(fi.number)): 1026 # Matches API & version #s being generated. Mark for 1027 # emission and add to the features[] list . 1028 # @@ Could use 'declared' instead of 'emit'? 1029 fi.emit = (regEmitVersions.match(fi.number) != None) 1030 features.append(fi) 1031 if (not fi.emit): 1032 self.gen.logMsg('diag', '*** NOT tagging feature api =', api, 1033 'name =', fi.name, 'number =', fi.number, 1034 'for emission (does not match emitversions pattern)') 1035 else: 1036 self.gen.logMsg('diag', '*** NOT including feature api =', api, 1037 'name =', fi.name, 'number =', fi.number, 1038 '(does not match requested versions)') 1039 else: 1040 self.gen.logMsg('diag', '*** NOT including feature api =', api, 1041 'name =', fi.name, 1042 '(does not match requested API)') 1043 if (not apiMatch): 1044 self.gen.logMsg('warn', '*** No matching API versions found!') 1045 # 1046 # Get all matching extensions & add to the list. 1047 # Start with extensions tagged with 'api' pattern matching the API 1048 # being generated. Add extensions matching the pattern specified in 1049 # regExtensions, then remove extensions matching the pattern 1050 # specified in regRemoveExtensions 1051 for key in self.extdict: 1052 ei = self.extdict[key] 1053 extName = ei.name 1054 include = False 1055 # 1056 # Include extension if defaultExtensions is not None and if the 1057 # 'supported' attribute matches defaultExtensions. The regexp in 1058 # 'supported' must exactly match defaultExtensions, so bracket 1059 # it with ^(pat)$. 1060 pat = '^(' + ei.elem.get('supported') + ')$' 1061 if (self.genOpts.defaultExtensions and 1062 re.match(pat, self.genOpts.defaultExtensions)): 1063 self.gen.logMsg('diag', '*** Including extension', 1064 extName, "(defaultExtensions matches the 'supported' attribute)") 1065 include = True 1066 # 1067 # Include additional extensions if the extension name matches 1068 # the regexp specified in the generator options. This allows 1069 # forcing extensions into an interface even if they're not 1070 # tagged appropriately in the registry. 1071 if (regAddExtensions.match(extName) != None): 1072 self.gen.logMsg('diag', '*** Including extension', 1073 extName, '(matches explicitly requested extensions to add)') 1074 include = True 1075 # Remove extensions if the name matches the regexp specified 1076 # in generator options. This allows forcing removal of 1077 # extensions from an interface even if they're tagged that 1078 # way in the registry. 1079 if (regRemoveExtensions.match(extName) != None): 1080 self.gen.logMsg('diag', '*** Removing extension', 1081 extName, '(matches explicitly requested extensions to remove)') 1082 include = False 1083 # 1084 # If the extension is to be included, add it to the 1085 # extension features list. 1086 if (include): 1087 ei.emit = True 1088 features.append(ei) 1089 else: 1090 self.gen.logMsg('diag', '*** NOT including extension', 1091 extName, '(does not match api attribute or explicitly requested extensions)') 1092 # 1093 # Sort the extension features list, if a sort procedure is defined 1094 if (self.genOpts.sortProcedure): 1095 self.genOpts.sortProcedure(features) 1096 # 1097 # Pass 1: loop over requested API versions and extensions tagging 1098 # types/commands/features as required (in an <require> block) or no 1099 # longer required (in an <exclude> block). It is possible to remove 1100 # a feature in one version and restore it later by requiring it in 1101 # a later version. 1102 # If a profile other than 'None' is being generated, it must 1103 # match the profile attribute (if any) of the <require> and 1104 # <remove> tags. 1105 self.gen.logMsg('diag', '*** PASS 1: TAG FEATURES ********************************************') 1106 for f in features: 1107 self.gen.logMsg('diag', '*** PASS 1: Tagging required and removed features for', 1108 f.name) 1109 self.requireAndRemoveFeatures(f.elem, self.genOpts.apiname, self.genOpts.profile) 1110 # 1111 # Pass 2: loop over specified API versions and extensions printing 1112 # declarations for required things which haven't already been 1113 # generated. 1114 self.gen.logMsg('diag', '*** PASS 2: GENERATE INTERFACES FOR FEATURES ************************') 1115 self.gen.beginFile(self.genOpts) 1116 for f in features: 1117 self.gen.logMsg('diag', '*** PASS 2: Generating interface for', 1118 f.name) 1119 emit = self.emitFeatures = f.emit 1120 if (not emit): 1121 self.gen.logMsg('diag', '*** PASS 2: NOT declaring feature', 1122 f.elem.get('name'), 'because it is not tagged for emission') 1123 # Generate the interface (or just tag its elements as having been 1124 # emitted, if they haven't been). 1125 self.gen.beginFeature(f.elem, emit) 1126 self.generateRequiredInterface(f.elem) 1127 self.gen.endFeature() 1128 self.gen.endFile() 1129 # 1130 # apiReset - use between apiGen() calls to reset internal state 1131 # 1132 def apiReset(self): 1133 """Reset type/enum/command dictionaries before generating another API""" 1134 for type in self.typedict: 1135 self.typedict[type].resetState() 1136 for enum in self.enumdict: 1137 self.enumdict[enum].resetState() 1138 for cmd in self.cmddict: 1139 self.cmddict[cmd].resetState() 1140 for cmd in self.apidict: 1141 self.apidict[cmd].resetState() 1142 # 1143 # validateGroups - check that group= attributes match actual groups 1144 # 1145 def validateGroups(self): 1146 """Validate group= attributes on <param> and <proto> tags""" 1147 # Keep track of group names not in <group> tags 1148 badGroup = {} 1149 self.gen.logMsg('diag', '*** VALIDATING GROUP ATTRIBUTES ***') 1150 for cmd in self.reg.findall('commands/command'): 1151 proto = cmd.find('proto') 1152 funcname = cmd.find('proto/name').text 1153 if ('group' in proto.attrib.keys()): 1154 group = proto.get('group') 1155 # self.gen.logMsg('diag', '*** Command ', funcname, ' has return group ', group) 1156 if (group not in self.groupdict.keys()): 1157 # self.gen.logMsg('diag', '*** Command ', funcname, ' has UNKNOWN return group ', group) 1158 if (group not in badGroup.keys()): 1159 badGroup[group] = 1 1160 else: 1161 badGroup[group] = badGroup[group] + 1 1162 for param in cmd.findall('param'): 1163 pname = param.find('name') 1164 if (pname != None): 1165 pname = pname.text 1166 else: 1167 pname = type.get('name') 1168 if ('group' in param.attrib.keys()): 1169 group = param.get('group') 1170 if (group not in self.groupdict.keys()): 1171 # self.gen.logMsg('diag', '*** Command ', funcname, ' param ', pname, ' has UNKNOWN group ', group) 1172 if (group not in badGroup.keys()): 1173 badGroup[group] = 1 1174 else: 1175 badGroup[group] = badGroup[group] + 1 1176 if (len(badGroup.keys()) > 0): 1177 self.gen.logMsg('diag', '*** SUMMARY OF UNRECOGNIZED GROUPS ***') 1178 for key in sorted(badGroup.keys()): 1179 self.gen.logMsg('diag', ' ', key, ' occurred ', badGroup[key], ' times') 1180