mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-01-26 14:20:33 +00:00
82e0f83d43
* Bump API patch number and header version number to 40 for this update.
* There is a major build change in this release. We are now using the
Ruby-based ``asciidoctor'' implementation, rather than the Python-based
``asciidoc'' implementation, to process the specification. While the
actual specification markup changes were minimal, this requires a new
set of build tools and a very different installation process, especially
because we now use an experimental direct-to-PDF backend for Asciidoctor
instead of Docbook->dblatex->PDF. It is no longer possible to build the
Specification using asciidoc. See doc/specs/vulkan/README.adoc
for some guidance on installing the new toolchain components.
* There are some minor rendering issues in the PDF output due to teething
problems with the asciidoctor toolchain, especially with mathematical
equations. We are aware of these and working on them.
Github Issues:
* Updated sample code for the <<sparsememory-examples-basic,sparse
resource binding example>> (public issue 97).
* Modify line and point clipping behavior in the
<<vertexpostproc-clipping, Primitive Clipping>> section to allow for
pop-free behavior. The ability to check for which behavior is
implemented may be added a future feature or extension (public issue
113).
* Unify the discussions of implicit ordering throughout the spec, in
particular in the new sections <<drawing-primitive-order, Primitive
Order>>, <<primrast-order, Rasterization Order>>, and
<<synchronization-implicit, Implicit Synchronization Guarantees>>; the
discussion of <<synchronization-submission-order, submission order>>;
and references elsewhere to these sections (public issue 133).
* Clarify \<\<descriptorsets-compatibility,Pipeline Layout Compatibility>>
language and introduce the term ``identically defined'' (public issue
164).
* Add a dependency to the +VK_EXT_debug_marker+ extension that's needed to
reuse the object type enum from +VK_EXT_debug_report+, and moves the
definition of that enum into +VK_EXT_debug_report+ where it should be
(public issue 409).
* Remove redundant valid usage statement from slink:VkImageBlit (public
issue 421).
* Update GL_KHR_vulkan_glsl to allow the ternary operator to result in a
specialization constant (public issue 424).
* Fix valid usage for flink:VkPipelineShaderStageCreateInfo (public issue
426).
* Correct typo in New Objects list for <<VK_EXT_debug_report>> (public
issue 447).
Internal Issues:
* Moved to asciidoctor for spec builds (internal issue 121).
* Update style guide to describe where to put new extensions-specific
asciidoc files, and what to name them (internal issue 626).
* Add src/spec/indexExt.py to autogenerate registry index entries linking
into the 1.0-extensions specification, instead of maintaining the index
manually. (internal issue 642).
* Autogenerate extension dependencies and lists of all extensions and all
KHR extensions from the "supported" attributes in +vk.xml+. Execute
+make config/extDependency.sh+ from +doc/specs/vulkan+ when a supported
extension is added to vk.xml, to regenerate the dependency script. The
consequence is that specifying a single extension to the +makeExt+
script will automatically enable all extensions it depends on as well,
and that the +makeAllExts+ and +makeKHR+ scripts do not need to be
updated when a new extension is supported (internal issue 648).
* Put extension appendices all at the same asciidoc section level, so KHR
WSI extensions show up in the HTML index (internal issue 648).
Other Issues:
* Imbed images in the generated HTML specs instead of loading them from
the images/ directory.
* Fix missing EXT in extension name
(ename:VK_EXT_SWAPCHAIN_COLOR_SPACE_EXTENSION_NAME).
* Add new +VK_EXT_SMPTE_2086_metadata+ extension.
* In the <<platformCreateSurface_xlib,Xlib Surface>> section of the
+VK_KHR_xlib_surface+ specification, add language warning users that
they always need to call code:XinitThreads.
* Use the term "presentable image" (rather than "swapchain image")
consistently in +VK_KHR_swapchain+ and related extensions, and add a
glossary term defining it.
* Relocate the valid usage for samples of
flink:vkGetPhysicalDeviceSparseImageFormatProperties2KHR::pname:pFormatInfo
to be below the flink:VkPhysicalDeviceSparseImageFormatInfo2KHR
structure.
189 lines
6.6 KiB
Python
189 lines
6.6 KiB
Python
#!/usr/bin/python3
|
|
#
|
|
# Copyright (c) 2016-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.
|
|
|
|
import time
|
|
from datetime import timedelta, date
|
|
|
|
# This script builds a full release package including XHTML and PDF
|
|
# versions of the specification, including an optional list of
|
|
# extensions. Other files in the release directory are removed,
|
|
#including man pages, XHTML chunked, HTML, validity output, etc.
|
|
|
|
# The current branch must be fully committed and up to date when the
|
|
# script is run, with no outstanding un-added / un-committed files.
|
|
# After completing the build, suggestions for creating tags are made.
|
|
|
|
# Khronos extensions
|
|
KHRextensions = [
|
|
'VK_KHR_android_surface',
|
|
'VK_KHR_display',
|
|
'VK_KHR_display_swapchain',
|
|
'VK_KHR_get_physical_device_properties2',
|
|
'VK_KHR_maintenance1',
|
|
'VK_KHR_mir_surface',
|
|
'VK_KHR_shader_draw_parameters',
|
|
'VK_KHR_surface',
|
|
'VK_KHR_swapchain',
|
|
'VK_KHR_wayland_surface',
|
|
'VK_KHR_win32_surface',
|
|
'VK_KHR_xcb_surface',
|
|
'VK_KHR_xlib_surface'
|
|
]
|
|
|
|
# All published extensions
|
|
allExtensions = KHRextensions + [
|
|
'VK_AMD_draw_indirect_count',
|
|
'VK_AMD_gcn_shader',
|
|
'VK_AMD_gpu_shader_half_float',
|
|
'VK_AMD_negative_viewport_height',
|
|
'VK_AMD_rasterization_order',
|
|
'VK_AMD_shader_ballot',
|
|
'VK_AMD_shader_explicit_vertex_parameter',
|
|
'VK_AMD_shader_trinary_minmax',
|
|
'VK_EXT_acquire_xlib_display',
|
|
'VK_EXT_debug_marker',
|
|
'VK_EXT_debug_report',
|
|
'VK_EXT_display_surface_counter',
|
|
'VK_EXT_direct_mode_display',
|
|
'VK_EXT_display_control',
|
|
'VK_EXT_display_surface_counter',
|
|
'VK_EXT_shader_subgroup_ballot',
|
|
'VK_EXT_shader_subgroup_vote',
|
|
'VK_EXT_SMPTE2086_metadata',
|
|
'VK_EXT_swapchain_colorspace',
|
|
'VK_EXT_validation_flags',
|
|
'VK_IMG_filter_cubic',
|
|
'VK_NN_vi_surface',
|
|
'VK_NV_dedicated_allocation',
|
|
'VK_NV_external_memory',
|
|
'VK_NV_external_memory_capabilities',
|
|
'VK_NV_external_memory_win32',
|
|
'VK_NV_win32_keyed_mutex',
|
|
'VK_NV_glsl_shader',
|
|
'VK_NVX_device_generated_commands'
|
|
]
|
|
|
|
# Return the Vulkan release number, used for tags
|
|
def releaseNum():
|
|
return '$REVISION'
|
|
|
|
# Return a date for the current, or upcoming if not already, Friday,
|
|
# which is when releases happen
|
|
def buildOnFriday():
|
|
today = date.today()
|
|
friday = today + timedelta((4 - today.weekday()) % 7)
|
|
return friday
|
|
|
|
# label = textual label to use for target being generated
|
|
# extensions = list of extension names to include
|
|
# outdir = directory to generate specs in
|
|
# apititle = extra title to apply to the specification
|
|
# xmlDir = directory containing registry XML
|
|
# xmlTargets = targets to build in src/spec/
|
|
# specDir = directory containing spec source & Makefile
|
|
# specTargets = targets to build in doc/specs/vulkan/
|
|
# miscSrc = path to copy misc files from, if non-None
|
|
# miscDst = path to copy misc files to, if non-None
|
|
# needRefSources = True if ref pages must be extracted from the spec sources
|
|
def buildRelease(label, extensions, outdir,
|
|
apititle,
|
|
xmlDir, xmlTargets,
|
|
specDir, specTargets,
|
|
miscSrc = None, miscDst = None, needRefSources = False):
|
|
print('echo Info: Generating target=', label,
|
|
'outdir=' + outdir)
|
|
|
|
outarg = 'OUTDIR=' + outdir
|
|
|
|
if (extensions != None and len(extensions) > 0):
|
|
extarg = 'EXTENSIONS="' + ' '.join(extensions) + '"'
|
|
else:
|
|
extarg = ''
|
|
|
|
if (apititle != None):
|
|
titlearg = 'APITITLE="' + apititle + '"'
|
|
else:
|
|
titlearg = ''
|
|
|
|
# print('echo Info: Cleaning spec in', outdir)
|
|
print('(cd ', outdir, '&& rm -rf',
|
|
'html chunked pdf',
|
|
'man config checks',
|
|
'vkspec.html styleguide.html apispec.html apispec.pdf registry.html',
|
|
')')
|
|
|
|
# print('echo Info: Generating specversion.txt')
|
|
print('cd', specDir)
|
|
print('rm specversion.txt ; make specversion.txt')
|
|
|
|
# print('echo Info: Generating headers and spec include files')
|
|
print('cd', xmlDir)
|
|
print('make', outarg, xmlTargets)
|
|
|
|
# print('echo Info: Generating ref pages sources and spec targets')
|
|
print('cd', specDir)
|
|
print('make', outarg, 'clean')
|
|
# This is a temporary workaround for a dependency bug - if any of the
|
|
# specTargets require ref page sources, and they aren't already present
|
|
# at the time the make is invoked, that target will not be built.
|
|
if needRefSources:
|
|
print('make', outarg, extarg, 'man/apispec.txt')
|
|
# Now make the actual targets.
|
|
print('make -O -k -j 8',
|
|
outarg,
|
|
extarg,
|
|
titlearg,
|
|
'NOTEOPTS="-a implementation-guide"',
|
|
specTargets)
|
|
|
|
if (miscSrc != None and miscDst != None):
|
|
print('cp', miscSrc + '/*.txt', miscDst + '/')
|
|
|
|
print('')
|
|
|
|
# Build all target documents
|
|
# repoDir = path to the Vulkan git repo containing the specs
|
|
# outDir = path to the output base directory in which targets are generated
|
|
def buildBranch(targetDir, extensions, apititle,
|
|
xmlTargets, specTargets,
|
|
repoDir, outDir, needRefSources = False):
|
|
# Directory with vk.xml and generation tools
|
|
xmlDir = repoDir + '/src/spec'
|
|
# Directory with spec sources
|
|
specDir = repoDir + '/doc/specs/vulkan'
|
|
# Src/dst directories with misc. GLSL extension specs
|
|
miscSrc = repoDir + '/doc/specs/misc'
|
|
miscDst = outDir + '/misc'
|
|
|
|
buildRelease(targetDir, extensions, outDir + '/' + targetDir,
|
|
apititle,
|
|
xmlDir, xmlTargets, specDir, specTargets,
|
|
miscSrc, miscDst, needRefSources)
|
|
|
|
# Commands to tag the git branches
|
|
# releaseNum = release number of this spec update, to tag the tree with
|
|
# tagdate = date (used to be used to tag the tree with)
|
|
def createTags(releaseNum, tagdate):
|
|
# Tag date in YYYYMMDD format
|
|
now = tagdate.strftime('%Y%m%d')
|
|
|
|
print('echo To tag the spec branch for this release, execute the command:')
|
|
print('echo git tag -a -m \\"Tag Vulkan API specification for 1.0.' +
|
|
releaseNum, 'release\\"', 'v1.0.' + releaseNum + '-core')
|
|
#print('echo git tag -a -m \\"Tag Vulkan API specification for', now,
|
|
# 'release\\"', 'v1.0-core-' + now)
|
|
|