1#!/usr/bin/python3 -i
2#
3# Copyright 2013-2024 The Khronos Group Inc.
4#
5# SPDX-License-Identifier: Apache-2.0
6
7# Working-group-specific style conventions,
8# used in generation.
9
10import re
11import os
12
13from spec_tools.conventions import ConventionsBase
14
15# Modified from default implementation - see category_requires_validation() below
16CATEGORIES_REQUIRING_VALIDATION = set(('handle', 'enum', 'bitmask'))
17
18# Tokenize into "words" for structure types, approximately per spec "Implicit Valid Usage" section 2.7.2
19# This first set is for things we recognize explicitly as words,
20# as exceptions to the general regex.
21# Ideally these would be listed in the spec as exceptions, as OpenXR does.
22SPECIAL_WORDS = set((
23    '16Bit',  # VkPhysicalDevice16BitStorageFeatures
24    '2D',     # VkPhysicalDeviceImage2DViewOf3DFeaturesEXT
25    '3D',     # VkPhysicalDeviceImage2DViewOf3DFeaturesEXT
26    '8Bit',  # VkPhysicalDevice8BitStorageFeaturesKHR
27    'AABB',  # VkGeometryAABBNV
28    'ASTC',  # VkPhysicalDeviceTextureCompressionASTCHDRFeaturesEXT
29    'D3D12',  # VkD3D12FenceSubmitInfoKHR
30    'Float16',  # VkPhysicalDeviceShaderFloat16Int8FeaturesKHR
31    'ImagePipe',  # VkImagePipeSurfaceCreateInfoFUCHSIA
32    'Int64',  # VkPhysicalDeviceShaderAtomicInt64FeaturesKHR
33    'Int8',  # VkPhysicalDeviceShaderFloat16Int8FeaturesKHR
34    'MacOS',  # VkMacOSSurfaceCreateInfoMVK
35    'RGBA10X6', # VkPhysicalDeviceRGBA10X6FormatsFeaturesEXT
36    'Uint8',  # VkPhysicalDeviceIndexTypeUint8FeaturesEXT
37    'Win32',  # VkWin32SurfaceCreateInfoKHR
38))
39# A regex to match any of the SPECIAL_WORDS
40EXCEPTION_PATTERN = r'(?P<exception>{})'.format(
41    '|'.join('(%s)' % re.escape(w) for w in SPECIAL_WORDS))
42MAIN_RE = re.compile(
43    # the negative lookahead is to prevent the all-caps pattern from being too greedy.
44    r'({}|([0-9]+)|([A-Z][a-z]+)|([A-Z][A-Z]*(?![a-z])))'.format(EXCEPTION_PATTERN))
45
46
47class VulkanConventions(ConventionsBase):
48    @property
49    def null(self):
50        """Preferred spelling of NULL."""
51        return '`NULL`'
52
53    def formatVersion(self, name, apivariant, major, minor):
54        """Mark up an API version name as a link in the spec."""
55        version = f'{major}.{minor}'
56        if apivariant == 'VKSC':
57            # Vulkan SC has a different anchor pattern for version appendices
58            if version == '1.0':
59                return 'Vulkan SC 1.0'
60            else:
61                return f'<<versions-sc-{version}, Version SC {version}>>'
62        else:
63            return f'<<versions-{version}, Version {version}>>'
64
65    def formatExtension(self, name):
66        """Mark up an extension name as a link in the spec."""
67        return f'apiext:{name}'
68
69    @property
70    def struct_macro(self):
71        """Get the appropriate format macro for a structure.
72
73        Primarily affects generated valid usage statements.
74        """
75
76        return 'slink:'
77
78    @property
79    def constFlagBits(self):
80        """Returns True if static const flag bits should be generated, False if an enumerated type should be generated."""
81        return False
82
83    @property
84    def structtype_member_name(self):
85        """Return name of the structure type member"""
86        return 'sType'
87
88    @property
89    def nextpointer_member_name(self):
90        """Return name of the structure pointer chain member"""
91        return 'pNext'
92
93    @property
94    def valid_pointer_prefix(self):
95        """Return prefix to pointers which must themselves be valid"""
96        return 'valid'
97
98    def is_structure_type_member(self, paramtype, paramname):
99        """Determine if member type and name match the structure type member."""
100        return paramtype == 'VkStructureType' and paramname == self.structtype_member_name
101
102    def is_nextpointer_member(self, paramtype, paramname):
103        """Determine if member type and name match the next pointer chain member."""
104        return paramtype == 'void' and paramname == self.nextpointer_member_name
105
106    def generate_structure_type_from_name(self, structname):
107        """Generate a structure type name, like VK_STRUCTURE_TYPE_CREATE_INSTANCE_INFO"""
108
109        structure_type_parts = []
110        # Tokenize into "words"
111        for elem in MAIN_RE.findall(structname):
112            word = elem[0]
113            if word == 'Vk':
114                structure_type_parts.append('VK_STRUCTURE_TYPE')
115            else:
116                structure_type_parts.append(word.upper())
117        name = '_'.join(structure_type_parts)
118
119        # The simple-minded rules need modification for some structure names
120        subpats = [
121            [ r'_H_(26[45])_',              r'_H\1_' ],
122            [ r'_VULKAN_([0-9])([0-9])_',   r'_VULKAN_\1_\2_' ],
123            [ r'_VULKAN_SC_([0-9])([0-9])_',r'_VULKAN_SC_\1_\2_' ],
124            [ r'_DIRECT_FB_',               r'_DIRECTFB_' ],
125            [ r'_VULKAN_SC_10',             r'_VULKAN_SC_1_0' ],
126
127        ]
128
129        for subpat in subpats:
130            name = re.sub(subpat[0], subpat[1], name)
131        return name
132
133    @property
134    def warning_comment(self):
135        """Return warning comment to be placed in header of generated Asciidoctor files"""
136        return '// WARNING: DO NOT MODIFY! This file is automatically generated from the vk.xml registry'
137
138    @property
139    def file_suffix(self):
140        """Return suffix of generated Asciidoctor files"""
141        return '.adoc'
142
143    def api_name(self, spectype='api'):
144        """Return API or specification name for citations in ref pages.ref
145           pages should link to for
146
147           spectype is the spec this refpage is for: 'api' is the Vulkan API
148           Specification. Defaults to 'api'. If an unrecognized spectype is
149           given, returns None.
150        """
151        if spectype == 'api' or spectype is None:
152            return 'Vulkan'
153        else:
154            return None
155
156    @property
157    def api_prefix(self):
158        """Return API token prefix"""
159        return 'VK_'
160
161    @property
162    def write_contacts(self):
163        """Return whether contact list should be written to extension appendices"""
164        return True
165
166    @property
167    def write_refpage_include(self):
168        """Return whether refpage include should be written to extension appendices"""
169        return True
170
171    @property
172    def member_used_for_unique_vuid(self):
173        """Return the member name used in the VUID-...-...-unique ID."""
174        return self.structtype_member_name
175
176    def is_externsync_command(self, protoname):
177        """Returns True if the protoname element is an API command requiring
178           external synchronization
179        """
180        return protoname is not None and 'vkCmd' in protoname
181
182    def is_api_name(self, name):
183        """Returns True if name is in the reserved API namespace.
184        For Vulkan, these are names with a case-insensitive 'vk' prefix, or
185        a 'PFN_vk' function pointer type prefix.
186        """
187        return name[0:2].lower() == 'vk' or name[0:6] == 'PFN_vk'
188
189    def specURL(self, spectype='api'):
190        """Return public registry URL which ref pages should link to for the
191           current all-extensions HTML specification, so xrefs in the
192           asciidoc source that are not to ref pages can link into it
193           instead. N.b. this may need to change on a per-refpage basis if
194           there are multiple documents involved.
195        """
196        return 'https://registry.khronos.org/vulkan/specs/1.3-extensions/html/vkspec.html'
197
198    @property
199    def xml_api_name(self):
200        """Return the name used in the default API XML registry for the default API"""
201        return 'vulkan'
202
203    @property
204    def registry_path(self):
205        """Return relpath to the default API XML registry in this project."""
206        return 'xml/vk.xml'
207
208    @property
209    def specification_path(self):
210        """Return relpath to the Asciidoctor specification sources in this project."""
211        return '{generated}/meta'
212
213    @property
214    def special_use_section_anchor(self):
215        """Return asciidoctor anchor name in the API Specification of the
216        section describing extension special uses in detail."""
217        return 'extendingvulkan-compatibility-specialuse'
218
219    @property
220    def extension_index_prefixes(self):
221        """Return a list of extension prefixes used to group extension refpages."""
222        return ['VK_KHR', 'VK_EXT', 'VK']
223
224    @property
225    def unified_flag_refpages(self):
226        """Return True if Flags/FlagBits refpages are unified, False if
227           they are separate.
228        """
229        return False
230
231    @property
232    def spec_reflow_path(self):
233        """Return the path to the spec source folder to reflow"""
234        return os.getcwd()
235
236    @property
237    def spec_no_reflow_dirs(self):
238        """Return a set of directories not to automatically descend into
239           when reflowing spec text
240        """
241        return ('scripts', 'style')
242
243    @property
244    def zero(self):
245        return '`0`'
246
247    def category_requires_validation(self, category):
248        """Return True if the given type 'category' always requires validation.
249
250        Overridden because Vulkan does not require "valid" text for basetype
251        in the spec right now."""
252        return category in CATEGORIES_REQUIRING_VALIDATION
253
254    @property
255    def should_skip_checking_codes(self):
256        """Return True if more than the basic validation of return codes should
257        be skipped for a command.
258
259        Vulkan mostly relies on the validation layers rather than API
260        builtin error checking, so these checks are not appropriate.
261
262        For example, passing in a VkFormat parameter will not potentially
263        generate a VK_ERROR_FORMAT_NOT_SUPPORTED code."""
264
265        return True
266
267    def extension_file_path(self, name):
268        """Return file path to an extension appendix relative to a directory
269           containing all such appendices.
270           - name - extension name"""
271
272        return f'{name}{self.file_suffix}'
273
274    def valid_flag_bit(self, bitpos):
275        """Return True if bitpos is an allowed numeric bit position for
276           an API flag bit.
277
278           Vulkan uses 32 bit Vk*Flags types, and assumes C compilers may
279           cause Vk*FlagBits values with bit 31 set to result in a 64 bit
280           enumerated type, so disallows such flags."""
281        return bitpos >= 0 and bitpos < 31
282
283    @property
284    def extra_refpage_headers(self):
285        """Return any extra text to add to refpage headers."""
286        return 'include::{config}/attribs.adoc[]'
287
288    @property
289    def extra_refpage_body(self):
290        """Return any extra text (following the title) for generated
291           reference pages."""
292        return 'include::{generated}/specattribs.adoc[]'
293
294
295class VulkanSCConventions(VulkanConventions):
296
297    def specURL(self, spectype='api'):
298        """Return public registry URL which ref pages should link to for the
299           current all-extensions HTML specification, so xrefs in the
300           asciidoc source that are not to ref pages can link into it
301           instead. N.b. this may need to change on a per-refpage basis if
302           there are multiple documents involved.
303        """
304        return 'https://registry.khronos.org/vulkansc/specs/1.0-extensions/html/vkspec.html'
305
306    @property
307    def xml_api_name(self):
308        """Return the name used in the default API XML registry for the default API"""
309        return 'vulkansc'
310
311