mewin/vulkan-headers
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Update for Vulkan-Docs 1.1.120

Browse Source
This commit is contained in:
Jon Leech
2019-08-17 15:58:46 -07:00
committed by Jon Leech
parent 23b2e8e64b
commit 4ee33d2fbd
22 changed files with 598 additions and 346 deletions
Download Patch File Download Diff File Expand all files Collapse all files

254
registry/conventions.py
View File

@@ -17,35 +17,96 @@
# Base class for working-group-specific style conventions,
# used in generation.
from abc import ABCMeta, abstractmethod
from enum import Enum
ABC = ABCMeta('ABC', (object,), {})
# Type categories that respond "False" to isStructAlwaysValid
# basetype is home to typedefs like ..Bool32
CATEGORIES_REQUIRING_VALIDATION = set(('handle',
'enum',
'bitmask',
'basetype',
None))
class ConventionsBase(ABC):
# These are basic C types pulled in via openxr_platform_defines.h
TYPES_KNOWN_ALWAYS_VALID = set(('char',
'float',
'int8_t', 'uint8_t',
'int32_t', 'uint32_t',
'int64_t', 'uint64_t',
'size_t',
'uintptr_t',
'int',
))
class ProseListFormats(Enum):
"""A connective, possibly with a quantifier."""
AND = 0
EACH_AND = 1
OR = 2
ANY_OR = 3
@classmethod
def from_string(cls, s):
if s == 'or':
return cls.OR
if s == 'and':
return cls.AND
return None
@property
def connective(self):
if self in (ProseListFormats.OR, ProseListFormats.ANY_OR):
return 'or'
return 'and'
def quantifier(self, n):
"""Return the desired quantifier for a list of a given length."""
if self == ProseListFormats.ANY_OR:
if n > 1:
return 'any of '
elif self == ProseListFormats.EACH_AND:
if n > 2:
return 'each of '
if n == 2:
return 'both of '
return ''
class ConventionsBase:
"""WG-specific conventions."""
@abstractmethod
def __init__(self):
self._command_prefix = None
self._type_prefix = None
def formatExtension(self, name):
"""Mark up a name as an extension for the spec."""
"""Mark up a name as an extension for the spec.
Must implement."""
raise NotImplementedError
@property
@abstractmethod
def null(self):
"""Preferred spelling of NULL."""
raise NotImplementedError
def makeProseList(self, elements, connective='and'):
def makeProseList(self, elements, fmt=ProseListFormats.AND, with_verb=False, *args, **kwargs):
"""Make a (comma-separated) list for use in prose.
Adds a connective (by default, 'and')
before the last element if there are more than 1.
Adds the right one of "is" or "are" to the end if with_verb is true.
Optionally adds a quantifier (like 'any') before a list of 2 or more,
if specified by fmt.
Override with a different method or different call to
_implMakeProseList if you want to add a comma for two elements,
or not use a serial comma.
"""
return self._implMakeProseList(elements, connective)
return self._implMakeProseList(elements, fmt, with_verb, *args, **kwargs)
@property
def struct_macro(self):
@@ -55,20 +116,20 @@ class ConventionsBase(ABC):
"""
return 'sname:'
def makeStructName(self, name):
"""Prepend the appropriate format macro for a structure to a structure type name.
Uses struct_macro, so just override that if you want to change behavior.
"""
return self.struct_macro + name
@property
def external_macro(self):
"""Get the appropriate format macro for an external type like uint32_t.
May override.
"""
return 'basetype:'
return 'code:'
def makeStructName(self, name):
"""Prepend the appropriate format macro for a structure to a structure type name.
Uses struct_macro, so just override that if you want to change behavior.
"""
return self.struct_macro + name
def makeExternalTypeName(self, name):
"""Prepend the appropriate format macro for an external type like uint32_t to a type name.
@@ -77,7 +138,7 @@ class ConventionsBase(ABC):
"""
return self.external_macro + name
def _implMakeProseList(self, elements, connective, comma_for_two_elts=False, serial_comma=True):
def _implMakeProseList(self, elements, fmt, with_verb, comma_for_two_elts=False, serial_comma=True):
"""Internal-use implementation to make a (comma-separated) list for use in prose.
Adds a connective (by default, 'and')
@@ -85,48 +146,171 @@ class ConventionsBase(ABC):
and only includes commas if there are more than 2
(if comma_for_two_elts is False).
Adds the right one of "is" or "are" to the end if with_verb is true.
Optionally adds a quantifier (like 'any') before a list of 2 or more,
if specified by fmt.
Don't edit these defaults, override self.makeProseList().
"""
assert(serial_comma) # didn't implement what we didn't need
if isinstance(fmt, str):
fmt = ProseListFormats.from_string(fmt)
my_elts = list(elements)
if len(my_elts) > 1:
my_elts[-1] = '{} {}'.format(connective, my_elts[-1])
my_elts[-1] = '{} {}'.format(fmt.connective, my_elts[-1])
if not comma_for_two_elts and len(my_elts) <= 2:
return ' '.join(my_elts)
return ', '.join(my_elts)
prose = ' '.join(my_elts)
else:
prose = ', '.join(my_elts)
quantifier = fmt.quantifier(len(my_elts))
parts = [quantifier, prose]
if with_verb:
if len(my_elts) > 1:
parts.append(' are')
else:
parts.append(' is')
return ''.join(parts)
@property
@abstractmethod
def file_suffix(self):
"""Return suffix of generated Asciidoctor files"""
raise NotImplementedError
@abstractmethod
def api_name(self, spectype = None):
"""Return API name"""
def api_name(self, spectype=None):
"""Return API or specification name for citations in ref pages.
spectype is the spec this refpage is for.
'api' (the default value) is the main API Specification.
If an unrecognized spectype is given, returns None.
Must implement."""
raise NotImplementedError
def should_insert_may_alias_macro(self, genOpts):
"""Return true if we should insert a "may alias" macro in this file.
Only used by OpenXR right now."""
return False
@property
def command_prefix(self):
"""Return the expected prefix of commands/functions.
Implemented in terms of api_prefix."""
if not self._command_prefix:
self._command_prefix = self.api_prefix[:].replace('_', '').lower()
return self._command_prefix
@property
def type_prefix(self):
"""Return the expected prefix of type names.
Implemented in terms of command_prefix (and in turn, api_prefix)."""
if not self._type_prefix:
self._type_prefix = ''.join(
(self.command_prefix[0:1].upper(), self.command_prefix[1:]))
return self._type_prefix
@property
@abstractmethod
def api_prefix(self):
"""Return API token prefix"""
"""Return API token prefix.
Typically two uppercase letters followed by an underscore.
Must implement."""
raise NotImplementedError
@property
@abstractmethod
def api_version_prefix(self):
"""Return API core version token prefix"""
raise NotImplementedError
"""Return API core version token prefix.
Implemented in terms of api_prefix.
May override."""
return self.api_prefix + 'VERSION_'
@property
@abstractmethod
def KHR_prefix(self):
"""Return extension name prefix for KHR extensions"""
raise NotImplementedError
"""Return extension name prefix for KHR extensions.
Implemented in terms of api_prefix.
May override."""
return self.api_prefix + 'KHR_'
@property
@abstractmethod
def EXT_prefix(self):
"""Return extension name prefix for EXT extensions"""
raise NotImplementedError
"""Return extension name prefix for EXT extensions.
Implemented in terms of api_prefix.
May override."""
return self.api_prefix + 'EXT_'
def writeFeature(self, featureExtraProtect, filename):
"""Return True if OutputGenerator.endFeature should write this feature.
Defaults to always True.
Used in COutputGenerator.
May override."""
return True
def requires_error_validation(self, return_type):
"""Return True if the return_type element is an API result code
requiring error validation.
Defaults to always False.
May override."""
return False
@property
def required_errors(self):
"""Return a list of required error codes for validation.
Defaults to an empty list.
May override."""
return []
def is_voidpointer_alias(self, tag, text, tail):
"""Return True if the declaration components (tag,text,tail) of an
element represents a void * type.
Defaults to a reasonable implementation.
May override."""
return tag == 'type' and text == 'void' and tail.startswith('*')
def make_voidpointer_alias(self, tail):
"""Reformat a void * declaration to include the API alias macro.
Defaults to a no-op.
Must override if you actually want to use this feature in your project."""
return tail
def category_requires_validation(self, category):
"""Return True if the given type 'category' always requires validation.
Defaults to a reasonable implementation.
May override."""
return category in CATEGORIES_REQUIRING_VALIDATION
def type_always_valid(self, typename):
"""Return True if the given type name is always valid (never requires validation).
This is for things like integers.
Defaults to a reasonable implementation.
May override."""
return typename in TYPES_KNOWN_ALWAYS_VALID