def makeGenOpts(extensions=[],
removeExtensions=[],
protect=True,
directory='.'):
global genOpts
genOpts = {}
# Descriptive names for various regexp patterns used to select
# versions and extensions
allVersions = allExtensions = '.*'
noVersions = noExtensions = None
addExtensions = makeREstring(extensions)
removeExtensions = makeREstring(removeExtensions)
# Copyright text prefixing all headers (list of strings).
prefixStrings = [
'/*', '** Copyright (c) 2015-2017 The Khronos Group Inc.', '**',
'** Licensed under the Apache License, Version 2.0 (the "License");',
'** you may not use this file except in compliance with the License.',
'** You may obtain a copy of the License at', '**',
'** http://www.apache.org/licenses/LICENSE-2.0', '**',
'** Unless required by applicable law or agreed to in writing, software',
'** distributed under the License is distributed on an "AS IS" BASIS,',
'** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.',
'** See the License for the specific language governing permissions and',
'** limitations under the License.', '*/', ''
]
# Text specific to Vulkan headers
vkPrefixStrings = [
'/*',
'** This header is generated from the Khronos Vulkan XML API Registry.',
'**', '*/', ''
]
# Defaults for generating re-inclusion protection wrappers (or not)
protectFile = protect
protectFeature = protect
protectProto = protect
# Header for core API + extensions.
# To generate just the core API,
# change to 'defaultExtensions = None' below.
genOpts['vulkan.h'] = [
COutputGenerator,
CGeneratorOptions(filename='vulkan.h',
directory=directory,
apiname='vulkan',
profile=None,
versions=allVersions,
emitversions=allVersions,
defaultExtensions='vulkan',
addExtensions=None,
removeExtensions=None,
prefixText=prefixStrings + vkPrefixStrings,
genFuncPointers=True,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='VK_NO_PROTOTYPES',
apicall='VKAPI_ATTR ',
apientry='VKAPI_CALL ',
apientryp='VKAPI_PTR *',
alignFuncParam=48)
]
# API include files for spec and ref pages
# Overwrites include subdirectories in spec source tree
# The generated include files do not include the calling convention
# macros (apientry etc.), unlike the header files.
# Because the 1.0 core branch includes ref pages for extensions,
# all the extension interfaces need to be generated, even though
# none are used by the core spec itself.
genOpts['apiinc'] = [
DocOutputGenerator,
DocGeneratorOptions(filename='timeMarker',
directory=directory,
apiname='vulkan',
profile=None,
versions=allVersions,
emitversions=allVersions,
defaultExtensions=None,
addExtensions=addExtensions,
removeExtensions=removeExtensions,
prefixText=prefixStrings + vkPrefixStrings,
apicall='',
apientry='',
apientryp='*',
alignFuncParam=48,
expandEnumerants=False)
]
# API names to validate man/api spec includes & links
genOpts['vkapi.py'] = [
PyOutputGenerator,
DocGeneratorOptions(filename='vkapi.py',
directory=directory,
apiname='vulkan',
profile=None,
versions=allVersions,
emitversions=allVersions,
defaultExtensions=None,
addExtensions=addExtensions,
removeExtensions=removeExtensions)
]
# API validity files for spec
genOpts['validinc'] = [
ValidityOutputGenerator,
DocGeneratorOptions(filename='timeMarker',
directory=directory,
apiname='vulkan',
profile=None,
versions=allVersions,
emitversions=allVersions,
defaultExtensions=None,
addExtensions=addExtensions,
removeExtensions=removeExtensions)
]
# API host sync table files for spec
genOpts['hostsyncinc'] = [
HostSynchronizationOutputGenerator,
DocGeneratorOptions(filename='timeMarker',
directory=directory,
apiname='vulkan',
profile=None,
versions=allVersions,
emitversions=allVersions,
defaultExtensions=None,
addExtensions=addExtensions,
removeExtensions=removeExtensions)
]
# Extension stub source dispatcher
genOpts['vulkan_ext.c'] = [
ExtensionStubSourceOutputGenerator,
CGeneratorOptions(filename='vulkan_ext.c',
directory=directory,
apiname='vulkan',
profile=None,
versions=allVersions,
emitversions=None,
defaultExtensions=None,
addExtensions='.*',
removeExtensions=removeExtensions,
prefixText=prefixStrings + vkPrefixStrings,
alignFuncParam=48)
]
# Extension metainformation for spec extension appendices
genOpts['extinc'] = [
ExtensionMetaDocOutputGenerator,
ExtensionMetaDocGeneratorOptions(filename='timeMarker',
directory=directory,
apiname='vulkan',
profile=None,
versions=allVersions,
emitversions=None,
defaultExtensions='vulkan',
addExtensions=None,
removeExtensions=None)
]
def makeGenOpts(args):
"""Returns a directory of [ generator function, generator options ] indexed
by specified short names. The generator options incorporate the following
parameters:
args is an parsed argument object; see below for the fields that are used."""
global genOpts
genOpts = {}
# Default class of extensions to include, or None
defaultExtensions = args.defaultExtensions
# Additional extensions to include (list of extensions)
extensions = args.extension
# Extensions to remove (list of extensions)
removeExtensions = args.removeExtensions
# Extensions to emit (list of extensions)
emitExtensions = args.emitExtensions
# Features to include (list of features)
features = args.feature
# Whether to disable inclusion protect in headers
protect = args.protect
# Output target directory
directory = args.directory
# Path to generated files, particularly api.py
genpath = args.genpath
# Descriptive names for various regexp patterns used to select
# versions and extensions
allFeatures = allExtensions = r'.*'
# Turn lists of names/patterns into matching regular expressions
addExtensionsPat = makeREstring(extensions, None)
removeExtensionsPat = makeREstring(removeExtensions, None)
emitExtensionsPat = makeREstring(emitExtensions, allExtensions)
featuresPat = makeREstring(features, allFeatures)
# Copyright text prefixing all headers (list of strings).
prefixStrings = [
'/*', '** Copyright (c) 2015-2020 The Khronos Group Inc.', '**',
'** SPDX-License-Identifier: Apache-2.0', '*/', ''
]
# Text specific to Vulkan headers
vkPrefixStrings = [
'/*',
'** This header is generated from the Khronos Vulkan XML API Registry.',
'**', '*/', ''
]
# Defaults for generating re-inclusion protection wrappers (or not)
protectFile = protect
# An API style conventions object
conventions = VulkanConventions()
# API include files for spec and ref pages
# Overwrites include subdirectories in spec source tree
# The generated include files do not include the calling convention
# macros (apientry etc.), unlike the header files.
# Because the 1.0 core branch includes ref pages for extensions,
# all the extension interfaces need to be generated, even though
# none are used by the core spec itself.
genOpts['apiinc'] = [
DocOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='timeMarker',
directory=directory,
genpath=genpath,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + vkPrefixStrings,
apicall='',
apientry='',
apientryp='*',
alignFuncParam=48,
expandEnumerants=False)
]
# Python representation of API information, used by scripts that
# don't need to load the full XML.
genOpts['api.py'] = [
PyOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='api.py',
directory=directory,
genpath=None,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
reparentEnums=False)
]
# API validity files for spec
genOpts['validinc'] = [
ValidityOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='timeMarker',
directory=directory,
genpath=None,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat)
]
# API host sync table files for spec
genOpts['hostsyncinc'] = [
HostSynchronizationOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='timeMarker',
directory=directory,
genpath=None,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
reparentEnums=False)
]
# Extension metainformation for spec extension appendices
# Includes all extensions by default, but only so that the generated
# 'promoted_extensions_*' files refer to all extensions that were
# promoted to a core version.
genOpts['extinc'] = [
ExtensionMetaDocOutputGenerator,
ExtensionMetaDocGeneratorOptions(conventions=conventions,
filename='timeMarker',
directory=directory,
genpath=None,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=None,
defaultExtensions=defaultExtensions,
addExtensions=addExtensionsPat,
removeExtensions=None,
emitExtensions=emitExtensionsPat)
]
# Version and extension interface docs for version/extension appendices
# Includes all extensions by default.
genOpts['interfaceinc'] = [
InterfaceDocGenerator,
DocGeneratorOptions(conventions=conventions,
filename='timeMarker',
directory=directory,
genpath=None,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
reparentEnums=False)
]
# Platform extensions, in their own header files
# Each element of the platforms[] array defines information for
# generating a single platform:
# [0] is the generated header file name
# [1] is the set of platform extensions to generate
# [2] is additional extensions whose interfaces should be considered,
# but suppressed in the output, to avoid duplicate definitions of
# dependent types like VkDisplayKHR and VkSurfaceKHR which come from
# non-platform extensions.
# Track all platform extensions, for exclusion from vulkan_core.h
allPlatformExtensions = []
# Extensions suppressed for all WSI platforms (WSI extensions required
# by all platforms)
commonSuppressExtensions = ['VK_KHR_display', 'VK_KHR_swapchain']
# Extensions required and suppressed for beta "platform". This can
# probably eventually be derived from the requires= attributes of
# the extension blocks.
betaRequireExtensions = [
'VK_KHR_ray_tracing', 'VK_KHR_deferred_host_operations',
'VK_KHR_pipeline_library'
]
betaSuppressExtensions = ['VK_NV_ray_tracing']
platforms = [
[
'vulkan_android.h',
[
'VK_KHR_android_surface',
'VK_ANDROID_external_memory_android_hardware_buffer'
], commonSuppressExtensions
],
[
'vulkan_fuchsia.h', ['VK_FUCHSIA_imagepipe_surface'],
commonSuppressExtensions
],
[
'vulkan_ggp.h',
['VK_GGP_stream_descriptor_surface', 'VK_GGP_frame_token'],
commonSuppressExtensions
],
['vulkan_ios.h', ['VK_MVK_ios_surface'], commonSuppressExtensions],
['vulkan_macos.h', ['VK_MVK_macos_surface'], commonSuppressExtensions],
['vulkan_vi.h', ['VK_NN_vi_surface'], commonSuppressExtensions],
[
'vulkan_wayland.h', ['VK_KHR_wayland_surface'],
commonSuppressExtensions
],
[
'vulkan_win32.h',
['VK_.*_win32(|_.*)', 'VK_EXT_full_screen_exclusive'],
commonSuppressExtensions + [
'VK_KHR_external_semaphore',
'VK_KHR_external_memory_capabilities',
'VK_KHR_external_fence',
'VK_KHR_external_fence_capabilities',
'VK_KHR_get_surface_capabilities2',
'VK_NV_external_memory_capabilities',
]
],
['vulkan_xcb.h', ['VK_KHR_xcb_surface'], commonSuppressExtensions],
['vulkan_xlib.h', ['VK_KHR_xlib_surface'], commonSuppressExtensions],
[
'vulkan_xlib_xrandr.h', ['VK_EXT_acquire_xlib_display'],
commonSuppressExtensions
],
['vulkan_metal.h', ['VK_EXT_metal_surface'], commonSuppressExtensions],
['vulkan_beta.h', betaRequireExtensions, betaSuppressExtensions],
]
for platform in platforms:
headername = platform[0]
allPlatformExtensions += platform[1]
addPlatformExtensionsRE = makeREstring(platform[1] + platform[2],
strings_are_regex=True)
emitPlatformExtensionsRE = makeREstring(platform[1],
strings_are_regex=True)
opts = CGeneratorOptions(conventions=conventions,
filename=headername,
directory=directory,
genpath=None,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=None,
defaultExtensions=None,
addExtensions=addPlatformExtensionsRE,
removeExtensions=None,
emitExtensions=emitPlatformExtensionsRE,
prefixText=prefixStrings + vkPrefixStrings,
genFuncPointers=True,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='VK_NO_PROTOTYPES',
apicall='VKAPI_ATTR ',
apientry='VKAPI_CALL ',
apientryp='VKAPI_PTR *',
alignFuncParam=48)
genOpts[headername] = [COutputGenerator, opts]
# Header for core API + extensions.
# To generate just the core API,
# change to 'defaultExtensions = None' below.
#
# By default this adds all enabled, non-platform extensions.
# It removes all platform extensions (from the platform headers options
# constructed above) as well as any explicitly specified removals.
removeExtensionsPat = makeREstring(allPlatformExtensions +
removeExtensions,
None,
strings_are_regex=True)
genOpts['vulkan_core.h'] = [
COutputGenerator,
CGeneratorOptions(conventions=conventions,
filename='vulkan_core.h',
directory=directory,
genpath=None,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=defaultExtensions,
addExtensions=None,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + vkPrefixStrings,
genFuncPointers=True,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='VK_NO_PROTOTYPES',
apicall='VKAPI_ATTR ',
apientry='VKAPI_CALL ',
apientryp='VKAPI_PTR *',
alignFuncParam=48)
]
# Unused - vulkan10.h target.
# It is possible to generate a header with just the Vulkan 1.0 +
# extension interfaces defined, but since the promoted KHR extensions
# are now defined in terms of the 1.1 interfaces, such a header is very
# similar to vulkan_core.h.
genOpts['vulkan10.h'] = [
COutputGenerator,
CGeneratorOptions(conventions=conventions,
filename='vulkan10.h',
directory=directory,
genpath=None,
apiname='vulkan',
profile=None,
versions='VK_VERSION_1_0',
emitversions='VK_VERSION_1_0',
defaultExtensions=None,
addExtensions=None,
removeExtensions=None,
emitExtensions=None,
prefixText=prefixStrings + vkPrefixStrings,
genFuncPointers=True,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='VK_NO_PROTOTYPES',
apicall='VKAPI_ATTR ',
apientry='VKAPI_CALL ',
apientryp='VKAPI_PTR *',
alignFuncParam=48)
]
# Unused - vulkan11.h target.
# It is possible to generate a header with just the Vulkan 1.0 +
# extension interfaces defined, but since the promoted KHR extensions
# are now defined in terms of the 1.1 interfaces, such a header is very
# similar to vulkan_core.h.
genOpts['vulkan11.h'] = [
COutputGenerator,
CGeneratorOptions(conventions=conventions,
filename='vulkan11.h',
directory=directory,
genpath=None,
apiname='vulkan',
profile=None,
versions='^VK_VERSION_1_[01]$',
emitversions='^VK_VERSION_1_[01]$',
defaultExtensions=None,
addExtensions=None,
removeExtensions=None,
emitExtensions=None,
prefixText=prefixStrings + vkPrefixStrings,
genFuncPointers=True,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='VK_NO_PROTOTYPES',
apicall='VKAPI_ATTR ',
apientry='VKAPI_CALL ',
apientryp='VKAPI_PTR *',
alignFuncParam=48)
]
genOpts['alias.h'] = [
COutputGenerator,
CGeneratorOptions(conventions=conventions,
filename='alias.h',
directory=directory,
genpath=None,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=defaultExtensions,
addExtensions=None,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=None,
genFuncPointers=False,
protectFile=False,
protectFeature=False,
protectProto='',
protectProtoStr='',
apicall='',
apientry='',
apientryp='',
alignFuncParam=36)
]
def makeGenOpts(args):
"""Returns a directory of [ generator function, generator options ] indexed
by specified short names. The generator options incorporate the following
parameters:
args is an parsed argument object; see below for the fields that are used."""
global genOpts
genOpts = {}
# Default class of extensions to include, or None
defaultExtensions = args.defaultExtensions
# Additional extensions to include (list of extensions)
extensions = args.extension
# Extensions to remove (list of extensions)
removeExtensions = args.removeExtensions
# Extensions to emit (list of extensions)
emitExtensions = args.emitExtensions
# Features to include (list of features)
features = args.feature
# Whether to disable inclusion protect in headers
protect = args.protect
# Output target directory
directory = args.directory
# Descriptive names for various regexp patterns used to select
# versions and extensions
allFeatures = allExtensions = r'.*'
# Turn lists of names/patterns into matching regular expressions
addExtensionsPat = makeREstring(extensions, None)
removeExtensionsPat = makeREstring(removeExtensions, None)
emitExtensionsPat = makeREstring(emitExtensions, allExtensions)
featuresPat = makeREstring(features, allFeatures)
# Copyright text prefixing all headers (list of strings).
prefixStrings = [
'/*', '** Copyright (c) 2017-2020 The Khronos Group Inc.', '**',
'** SPDX-License-Identifier: Apache-2.0', '**',
'** Licensed under the Apache License, Version 2.0 (the "License");',
'** you may not use this file except in compliance with the License.',
'** You may obtain a copy of the License at', '**',
'** http://www.apache.org/licenses/LICENSE-2.0', '**',
'** Unless required by applicable law or agreed to in writing, software',
'** distributed under the License is distributed on an "AS IS" BASIS,',
'** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.',
'** See the License for the specific language governing permissions and',
'** limitations under the License.', '*/', ''
]
# Text specific to OpenXR headers
xrPrefixStrings = [
'/*',
'** This header is generated from the Khronos OpenXR XML API Registry.',
'**', '*/', ''
]
# Include the non-platform openxr header in the platform header.
platformPrefixStrings = ['#include "openxr.h"']
# Defaults for generating re-inclusion protection wrappers (or not)
protectFile = protect
# An API style conventions object
conventions = OpenXRConventions()
# OpenXR 1.0 - header for core API + extensions.
# To generate just the core API,
# change to 'defaultExtensions = None' below.
genOpts['openxr.h'] = [
COutputGenerator,
CGeneratorOptions(conventions=conventions,
filename='openxr.h',
directory=directory,
apiname='openxr',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions='openxr',
addExtensions=None,
removeExtensions=None,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + xrPrefixStrings,
genFuncPointers=True,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='XR_NO_PROTOTYPES',
apicall='XRAPI_ATTR ',
apientry='XRAPI_CALL ',
apientryp='XRAPI_PTR *',
alignFuncParam=48,
genAliasMacro=True,
aliasMacro='XR_MAY_ALIAS')
]
# OpenXR platform header for Graphics API and Platform extensions.
genOpts['openxr_platform.h'] = [
COutputGenerator,
CGeneratorOptions(conventions=conventions,
filename='openxr_platform.h',
directory=directory,
apiname='openxr',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions='openxr',
addExtensions=None,
removeExtensions=None,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + xrPrefixStrings +
platformPrefixStrings,
genFuncPointers=True,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='XR_NO_PROTOTYPES',
apicall='XRAPI_ATTR ',
apientry='XRAPI_CALL ',
apientryp='XRAPI_PTR *',
alignFuncParam=48,
genAliasMacro=True,
aliasMacro='XR_MAY_ALIAS')
]
# OpenXR platform header for Graphics API and Platform extensions.
genOpts['openxr_reflection.h'] = [
CReflectionOutputGenerator,
CGeneratorOptions(conventions=conventions,
filename='openxr_reflection.h',
directory=directory,
apiname='openxr',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions='openxr',
addExtensions=None,
removeExtensions=None,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + xrPrefixStrings +
platformPrefixStrings,
genFuncPointers=True,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='XR_NO_PROTOTYPES',
apicall='XRAPI_ATTR ',
apientry='XRAPI_CALL ',
apientryp='XRAPI_PTR *',
alignFuncParam=48,
genAliasMacro=True,
aliasMacro='XR_MAY_ALIAS')
]
# OpenXR 1.0 - API include files for spec and ref pages
# Overwrites include subdirectories in spec source tree
# The generated include files do not include the calling convention
# macros (apientry etc.), unlike the header files.
# Because the 1.0 core branch includes ref pages for extensions,
# all the extension interfaces need to be generated, even though
# none are used by the core spec itself.
genOpts['apiinc'] = [
DocOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='apiinc',
directory=directory,
apiname='openxr',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + xrPrefixStrings,
apicall='',
apientry='',
apientryp='*',
alignFuncParam=48,
secondaryInclude=True,
expandEnumerants=False,
extEnumerantAdditions=True)
]
# API names to validate man/api spec includes & links
genOpts['xrapi.py'] = [
PyOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='xrapi.py',
directory=directory,
apiname='openxr',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat)
]
# Index chapter
genOpts['index.adoc'] = [
DocIndexOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='index.adoc',
directory=directory,
apiname='openxr',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat)
]
# Core API validity files for spec
genOpts['validinc'] = [
ValidityOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='validinc',
directory=directory,
apiname='openxr',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat)
]
# Core API host sync table files for spec
genOpts['hostsyncinc'] = [
HostSynchronizationOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='hostsyncinc',
directory=directory,
apiname='openxr',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat)
]
# Extension metainformation for spec extension appendices
genOpts['extinc'] = [
ExtensionMetaDocOutputGenerator,
ExtensionMetaDocGeneratorOptions(conventions=conventions,
filename='extinc',
directory=directory,
apiname='openxr',
profile=None,
versions=featuresPat,
emitversions=None,
defaultExtensions=defaultExtensions,
addExtensions=None,
removeExtensions=None,
emitExtensions=emitExtensionsPat)
]
def makeGenOpts(args):
global genOpts
genOpts = {}
# Default class of extensions to include, or None
defaultExtensions = args.defaultExtensions
# Additional extensions to include (list of extensions)
extensions = args.extension
# Extensions to remove (list of extensions)
removeExtensions = args.removeExtensions
# Extensions to emit (list of extensions)
emitExtensions = args.emitExtensions
# Features to include (list of features)
features = args.feature
# Whether to disable inclusion protect in headers
protect = args.protect
# Output target directory
directory = args.directory
# Descriptive names for various regexp patterns used to select
# versions and extensions
allFeatures = allExtensions = '.*'
noFeatures = noExtensions = None
# Turn lists of names/patterns into matching regular expressions
addExtensionsPat = makeREstring(extensions, None)
removeExtensionsPat = makeREstring(removeExtensions, None)
emitExtensionsPat = makeREstring(emitExtensions, allExtensions)
featuresPat = makeREstring(features, allFeatures)
# Copyright text prefixing all headers (list of strings).
prefixStrings = [
'/*', '** Copyright (c) 2015-2019 The Khronos Group Inc.', '**',
'** Licensed under the Apache License, Version 2.0 (the "License");',
'** you may not use this file except in compliance with the License.',
'** You may obtain a copy of the License at', '**',
'** http://www.apache.org/licenses/LICENSE-2.0', '**',
'** Unless required by applicable law or agreed to in writing, software',
'** distributed under the License is distributed on an "AS IS" BASIS,',
'** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.',
'** See the License for the specific language governing permissions and',
'** limitations under the License.', '*/', ''
]
# Text specific to Vulkan headers
vkPrefixStrings = [
'/*',
'** This header is generated from the Khronos Vulkan XML API Registry.',
'**', '*/', ''
]
# Defaults for generating re-inclusion protection wrappers (or not)
protectFile = protect
protectFeature = protect
protectProto = protect
# An API style conventions object
conventions = VulkanConventions()
# API include files for spec and ref pages
# Overwrites include subdirectories in spec source tree
# The generated include files do not include the calling convention
# macros (apientry etc.), unlike the header files.
# Because the 1.0 core branch includes ref pages for extensions,
# all the extension interfaces need to be generated, even though
# none are used by the core spec itself.
genOpts['apiinc'] = [
DocOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='timeMarker',
directory=directory,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + vkPrefixStrings,
apicall='',
apientry='',
apientryp='*',
alignFuncParam=48,
expandEnumerants=False)
]
# API names to validate man/api spec includes & links
genOpts['vkapi.py'] = [
PyOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='vkapi.py',
directory=directory,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat)
]
# API validity files for spec
genOpts['validinc'] = [
ValidityOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='timeMarker',
directory=directory,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat)
]
# API host sync table files for spec
genOpts['hostsyncinc'] = [
HostSynchronizationOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='timeMarker',
directory=directory,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat)
]
# Extension metainformation for spec extension appendices
genOpts['extinc'] = [
ExtensionMetaDocOutputGenerator,
ExtensionMetaDocGeneratorOptions(conventions=conventions,
filename='timeMarker',
directory=directory,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=None,
defaultExtensions=defaultExtensions,
addExtensions=None,
removeExtensions=None,
emitExtensions=emitExtensionsPat)
]
# Platform extensions, in their own header files
# Each element of the platforms[] array defines information for
# generating a single platform:
# [0] is the generated header file name
# [1] is the set of platform extensions to generate
# [2] is additional extensions whose interfaces should be considered,
# but suppressed in the output, to avoid duplicate definitions of
# dependent types like VkDisplayKHR and VkSurfaceKHR which come from
# non-platform extensions.
# Track all platform extensions, for exclusion from vulkan_core.h
allPlatformExtensions = []
# Extensions suppressed for all platforms.
# Covers common WSI extension types.
commonSuppressExtensions = ['VK_KHR_display', 'VK_KHR_swapchain']
platforms = [
[
'vulkan_android.h',
[
'VK_KHR_android_surface',
'VK_ANDROID_external_memory_android_hardware_buffer'
], commonSuppressExtensions
],
[
'vulkan_fuchsia.h', ['VK_FUCHSIA_imagepipe_surface'],
commonSuppressExtensions
],
[
'vulkan_ggp.h',
['VK_GGP_stream_descriptor_surface', 'VK_GGP_frame_token'],
commonSuppressExtensions
],
['vulkan_ios.h', ['VK_MVK_ios_surface'], commonSuppressExtensions],
['vulkan_macos.h', ['VK_MVK_macos_surface'], commonSuppressExtensions],
['vulkan_vi.h', ['VK_NN_vi_surface'], commonSuppressExtensions],
[
'vulkan_wayland.h', ['VK_KHR_wayland_surface'],
commonSuppressExtensions
],
[
'vulkan_win32.h',
['VK_.*_win32(|_.*)', 'VK_EXT_full_screen_exclusive'],
commonSuppressExtensions + [
'VK_KHR_external_semaphore',
'VK_KHR_external_memory_capabilities',
'VK_KHR_external_fence',
'VK_KHR_external_fence_capabilities',
'VK_KHR_get_surface_capabilities2',
'VK_NV_external_memory_capabilities',
]
],
['vulkan_xcb.h', ['VK_KHR_xcb_surface'], commonSuppressExtensions],
['vulkan_xlib.h', ['VK_KHR_xlib_surface'], commonSuppressExtensions],
[
'vulkan_xlib_xrandr.h', ['VK_EXT_acquire_xlib_display'],
commonSuppressExtensions
],
['vulkan_metal.h', ['VK_EXT_metal_surface'], commonSuppressExtensions],
]
for platform in platforms:
headername = platform[0]
allPlatformExtensions += platform[1]
addPlatformExtensionsRE = makeREstring(platform[1] + platform[2])
emitPlatformExtensionsRE = makeREstring(platform[1])
opts = CGeneratorOptions(conventions=conventions,
filename=headername,
directory=directory,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=None,
defaultExtensions=None,
addExtensions=addPlatformExtensionsRE,
removeExtensions=None,
emitExtensions=emitPlatformExtensionsRE,
prefixText=prefixStrings + vkPrefixStrings,
genFuncPointers=True,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='VK_NO_PROTOTYPES',
apicall='VKAPI_ATTR ',
apientry='VKAPI_CALL ',
apientryp='VKAPI_PTR *',
alignFuncParam=48,
genEnumBeginEndRange=True)
genOpts[headername] = [COutputGenerator, opts]
# Header for core API + extensions.
# To generate just the core API,
# change to 'defaultExtensions = None' below.
#
# By default this adds all enabled, non-platform extensions.
# It removes all platform extensions (from the platform headers options
# constructed above) as well as any explicitly specified removals.
removeExtensionsPat = makeREstring(
allPlatformExtensions + removeExtensions, None)
genOpts['vulkan_core.h'] = [
COutputGenerator,
CGeneratorOptions(conventions=conventions,
filename='vulkan_core.h',
directory=directory,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=defaultExtensions,
addExtensions=None,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + vkPrefixStrings,
genFuncPointers=True,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='VK_NO_PROTOTYPES',
apicall='VKAPI_ATTR ',
apientry='VKAPI_CALL ',
apientryp='VKAPI_PTR *',
alignFuncParam=48,
genEnumBeginEndRange=True)
]
# Unused - vulkan10.h target.
# It is possible to generate a header with just the Vulkan 1.0 +
# extension interfaces defined, but since the promoted KHR extensions
# are now defined in terms of the 1.1 interfaces, such a header is very
# similar to vulkan_core.h.
genOpts['vulkan10.h'] = [
COutputGenerator,
CGeneratorOptions(conventions=conventions,
filename='vulkan10.h',
directory=directory,
apiname='vulkan',
profile=None,
versions='VK_VERSION_1_0',
emitversions='VK_VERSION_1_0',
defaultExtensions=defaultExtensions,
addExtensions=None,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + vkPrefixStrings,
genFuncPointers=True,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='VK_NO_PROTOTYPES',
apicall='VKAPI_ATTR ',
apientry='VKAPI_CALL ',
apientryp='VKAPI_PTR *',
alignFuncParam=48)
]
genOpts['alias.h'] = [
COutputGenerator,
CGeneratorOptions(conventions=conventions,
filename='alias.h',
directory=directory,
apiname='vulkan',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=defaultExtensions,
addExtensions=None,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=None,
genFuncPointers=False,
protectFile=False,
protectFeature=False,
protectProto='',
protectProtoStr='',
apicall='',
apientry='',
apientryp='',
alignFuncParam=36)
]
def makeGenOpts(args):
"""Returns a directory of [ generator function, generator options ] indexed
by specified short names. The generator options incorporate the following
parameters:
args is an parsed argument object; see below for the fields that are used."""
global genOpts
genOpts = {}
# Default class of extensions to include, or None
defaultExtensions = args.defaultExtensions
# Additional extensions to include (list of extensions)
extensions = args.extension
# Extensions to remove (list of extensions)
removeExtensions = args.removeExtensions
# Extensions to emit (list of extensions)
emitExtensions = args.emitExtensions
# SPIR-V capabilities / features to emit (list of extensions & capabilities)
# emitSpirv = args.emitSpirv
# Features to include (list of features)
features = args.feature
# Whether to disable inclusion protect in headers
protect = args.protect
# Output target directory
directory = args.directory
# Path to generated files, particularly api.py
genpath = args.genpath
# Generate MISRA C-friendly headers
misracstyle = args.misracstyle
# Generate MISRA C++-friendly headers
misracppstyle = args.misracppstyle
# Descriptive names for various regexp patterns used to select
# versions and extensions
allSpirv = allFeatures = allExtensions = r'.*'
# Turn lists of names/patterns into matching regular expressions
addExtensionsPat = makeREstring(extensions, None)
removeExtensionsPat = makeREstring(removeExtensions, None)
emitExtensionsPat = makeREstring(emitExtensions, allExtensions)
# emitSpirvPat = makeREstring(emitSpirv, allSpirv)
featuresPat = makeREstring(features, allFeatures)
# Copyright text prefixing all headers (list of strings).
# The SPDX formatting below works around constraints of the 'reuse' tool
prefixStrings = [
'/*', '** Copyright 2015-2021 The Khronos Group Inc.', '**',
'** SPDX' + '-License-Identifier: Apache-2.0', '*/', ''
]
# Text specific to OpenCL headers
clPrefixStrings = [
'/*',
'** This header is generated from the Khronos OpenCL XML API Registry.',
'**', '*/', ''
]
# Defaults for generating re-inclusion protection wrappers (or not)
protectFile = protect
# An API style conventions object
conventions = APIConventions()
# API include files for spec and ref pages
# Overwrites include subdirectories in spec source tree
# The generated include files do not include the calling convention
# macros (apientry etc.), unlike the header files.
# Because the 1.0 core branch includes ref pages for extensions,
# all the extension interfaces need to be generated, even though
# none are used by the core spec itself.
genOpts['apiinc'] = [
DocOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='timeMarker',
directory=directory,
genpath=genpath,
apiname='opencl',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=defaultExtensions,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + clPrefixStrings,
apicall='',
apientry='',
apientryp='*',
alignFuncParam=0,
expandEnumerants=False)
]
# Python representation of API information, used by scripts that
# don't need to load the full XML.
genOpts['api.py'] = [
PyOutputGenerator,
DocGeneratorOptions(conventions=conventions,
filename='api.py',
directory=directory,
genpath=genpath,
apiname='opencl',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
reparentEnums=False)
]
# Extension metainformation for spec extension appendices
# Includes all extensions by default, but only so that the generated
# 'promoted_extensions_*' files refer to all extensions that were
# promoted to a core version.
genOpts['extinc'] = [
ExtensionMetaDocOutputGenerator,
ExtensionMetaDocGeneratorOptions(conventions=conventions,
filename='timeMarker',
directory=directory,
genpath=None,
apiname='opencl',
profile=None,
versions=featuresPat,
emitversions=None,
defaultExtensions=defaultExtensions,
addExtensions=addExtensionsPat,
removeExtensions=None,
emitExtensions=emitExtensionsPat)
]
# Platform extensions, in their own header files
# Each element of the platforms[] array defines information for
# generating a single platform:
# [0] is the generated header file name
# [1] is the set of platform extensions to generate
# [2] is additional extensions whose interfaces should be considered,
# but suppressed in the output, to avoid duplicate definitions of
# dependent types like VkDisplayKHR and VkSurfaceKHR which come from
# non-platform extensions.
# Track all platform extensions, for exclusion from vulkan_core.h
allPlatformExtensions = []
# # Extensions suppressed for all platforms.
# # Covers common WSI extension types.
# commonSuppressExtensions = [ 'VK_KHR_display', 'VK_KHR_swapchain' ]
#
# platforms = [
# [ 'vulkan_android.h', [ 'VK_KHR_android_surface',
# 'VK_ANDROID_external_memory_android_hardware_buffer'
# ], commonSuppressExtensions ],
# [ 'vulkan_fuchsia.h', [ 'VK_FUCHSIA_imagepipe_surface'], commonSuppressExtensions ],
# [ 'vulkan_ios.h', [ 'VK_MVK_ios_surface' ], commonSuppressExtensions ],
# [ 'vulkan_macos.h', [ 'VK_MVK_macos_surface' ], commonSuppressExtensions ],
# [ 'vulkan_vi.h', [ 'VK_NN_vi_surface' ], commonSuppressExtensions ],
# [ 'vulkan_wayland.h', [ 'VK_KHR_wayland_surface' ], commonSuppressExtensions ],
# [ 'vulkan_win32.h', [ 'VK_.*_win32(|_.*)' ], commonSuppressExtensions + [ 'VK_KHR_external_semaphore', 'VK_KHR_external_memory_capabilities', 'VK_KHR_external_fence', 'VK_KHR_external_fence_capabilities', 'VK_NV_external_memory_capabilities' ] ],
# [ 'vulkan_xcb.h', [ 'VK_KHR_xcb_surface' ], commonSuppressExtensions ],
# [ 'vulkan_xlib.h', [ 'VK_KHR_xlib_surface' ], commonSuppressExtensions ],
# [ 'vulkan_xlib_xrandr.h', [ 'VK_EXT_acquire_xlib_display' ], commonSuppressExtensions ],
# ]
#
# for platform in platforms:
# headername = platform[0]
#
# allPlatformExtensions += platform[1]
#
# addPlatformExtensionsRE = makeREstring(platform[1] + platform[2])
# emitPlatformExtensionsRE = makeREstring(platform[1])
#
# opts = CGeneratorOptions(
# filename = headername,
# directory = directory,
# apiname = 'vulkan',
# profile = None,
# versions = featuresPat,
# emitversions = None,
# defaultExtensions = None,
# addExtensions = addPlatformExtensionsRE,
# removeExtensions = None,
# emitExtensions = emitPlatformExtensionsRE,
# prefixText = prefixStrings + clPrefixStrings,
# genFuncPointers = True,
# protectFile = protectFile,
# protectFeature = False,
# protectProto = '#ifndef',
# protectProtoStr = 'VK_NO_PROTOTYPES',
# apicall = 'VKAPI_ATTR ',
# apientry = 'VKAPI_CALL ',
# apientryp = 'VKAPI_PTR *',
# alignFuncParam = 0)
#
# genOpts[headername] = [ COutputGenerator, opts ]
# Header for core API + extensions.
# To generate just the core API,
# change to 'defaultExtensions = None' below.
#
# By default this adds all enabled, non-platform extensions.
# It removes all platform extensions (from the platform headers options
# constructed above) as well as any explicitly specified removals.
removeExtensionsPat = makeREstring(allPlatformExtensions +
removeExtensions,
None,
strings_are_regex=True)
genOpts['cl.h'] = [
COutputGenerator,
CGeneratorOptions(conventions=conventions,
filename='cl.h',
directory=directory,
genpath=None,
apiname='opencl',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=defaultExtensions,
addExtensions=None,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + clPrefixStrings,
genFuncPointers=False,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='CL_NO_PROTOTYPES',
apicall='CL_API_ENTRY ',
apientry='CL_API_CALL ',
apientryp='CL_API_CALL *',
alignFuncParam=0,
misracstyle=misracstyle,
misracppstyle=misracppstyle)
]
def makeGenOpts(args):
global genOpts
genOpts = {}
# Default class of extensions to include, or None
defaultExtensions = args.defaultExtensions
# Additional extensions to include (list of extensions)
extensions = args.extension
# Extensions to remove (list of extensions)
removeExtensions = args.removeExtensions
# Extensions to emit (list of extensions)
emitExtensions = args.emitExtensions
# Features to include (list of features)
features = args.feature
# Whether to disable inclusion protect in headers
protect = args.protect
# Output target directory
directory = args.directory
# Descriptive names for various regexp patterns used to select
# versions and extensions
allFeatures = allExtensions = '.*'
noFeatures = noExtensions = None
# Turn lists of names/patterns into matching regular expressions
addExtensionsPat = makeREstring(extensions, None)
removeExtensionsPat = makeREstring(removeExtensions, None)
emitExtensionsPat = makeREstring(emitExtensions, allExtensions)
featuresPat = makeREstring(features, allFeatures)
# Copyright text prefixing all headers (list of strings).
prefixStrings = [
'/*', '** Copyright (c) 2015-2017 The Khronos Group Inc.', '**',
'** Licensed under the Apache License, Version 2.0 (the "License");',
'** you may not use this file except in compliance with the License.',
'** You may obtain a copy of the License at', '**',
'** http://www.apache.org/licenses/LICENSE-2.0', '**',
'** Unless required by applicable law or agreed to in writing, software',
'** distributed under the License is distributed on an "AS IS" BASIS,',
'** WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.',
'** See the License for the specific language governing permissions and',
'** limitations under the License.', '*/', ''
]
# Text specific to OpenVX headers
vxPrefixStrings = [
'/*',
'** This header is generated from the Khronos OpenVX XML API Registry.',
'**', '*/', ''
]
# Defaults for generating re-inclusion protection wrappers (or not)
protectFile = protect
protectFeature = protect
protectProto = protect
# API include files for spec and ref pages
# Overwrites include subdirectories in spec source tree
# The generated include files do not include the calling convention
# macros (apientry etc.), unlike the header files.
# Because the 1.0 core branch includes ref pages for extensions,
# all the extension interfaces need to be generated, even though
# none are used by the core spec itself.
genOpts['apiinc'] = [
DocOutputGenerator,
DocGeneratorOptions(
filename='timeMarker',
directory=directory,
apiname='openvx',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions='openvx',
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + vxPrefixStrings,
apientry='', #'VX_API_ENTRY ',
apicall='', #'VX_API_CALL ',
apicallp='*', #'VX_CALLBACK *',
alignFuncParam=48,
expandEnumerants=False)
]
# API names to validate man/api spec includes & links
genOpts['vxapi.py'] = [
PyOutputGenerator,
DocGeneratorOptions(filename='vxapi.py',
directory=directory,
apiname='openvx',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=None,
addExtensions=addExtensionsPat,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat)
]
# Headers for core API + extensions.
# To generate just the core API,
# change to 'defaultExtensions = None' below.
#
# By default this adds all enabled, non-platform extensions.
# It removes all platform extensions (from the platform headers options
# constructed above) as well as any explicitly specified removals.
# Headers for different elements of the core API
features = [
['_OPENVX_API_H_', 'vx_api.h'],
['_OPENVX_H_', 'vx.h'],
['_OPENVX_TYPES_H_', 'vx_types.h'],
['_OPENVX_UTILITY_H_', 'vxu.h'],
['_OPENVX_VENDORS_H_', 'vx_vendors.h'],
['_VX_HELPER_H_', 'vx_helper.h'],
['_OPENVX_IMPORT_H_', 'vx_import.h'],
['_OPENVX_KERNELS_H_', 'vx_kernels.h'],
]
for feature in features:
featureName = feature[0]
headername = feature[1]
featuresPat = makeREstring([featureName])
opts = CGeneratorOptions(
filename=headername,
directory=directory,
apiname='openvx',
profile=None,
versions=featuresPat,
emitversions=featuresPat,
defaultExtensions=defaultExtensions,
addExtensions=None,
removeExtensions=removeExtensionsPat,
emitExtensions=emitExtensionsPat,
prefixText=prefixStrings + vxPrefixStrings,
genFuncPointers=False,
protectFile=protectFile,
protectFeature=False,
protectProto='#ifndef',
protectProtoStr='VX_NO_PROTOTYPES',
apientry=' ', #'VX_API_ENTRY ',
apicall=' ', #'VX_API_CALL ',
apicallp=' *', #'VX_CALLBACK *',
alignFuncParam=30)
genOpts[headername] = [COutputGenerator, opts]
