Vulkan-Docs/doc/specs/vulkan/config/vulkan-macros/extension.rb

246 lines
4.9 KiB
Ruby
Raw Normal View History

Change log for February 10, 2017 Vulkan 1.0.40 spec update: * 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.
2017-02-11 04:37:39 +00:00
# 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.
require 'asciidoctor/extensions' unless RUBY_ENGINE == 'opal'
include ::Asciidoctor
class VulkanInlineMacroBase < Extensions::InlineMacroProcessor
use_dsl
using_format :short
end
class NormativeInlineMacroBase < VulkanInlineMacroBase
def text
'normative'
end
def process parent, target, attributes
'<strong class="purple">' + text + '</strong>'
end
end
class LinkInlineMacroBase < VulkanInlineMacroBase
def process parent, target, attributes
Change log for February 17, 2017 Vulkan 1.0.41 spec update: * Bump API patch number and header version number to 41 for this update. Github Issues: * Made all uses of `NULL` vs. code:VK_NULL_HANDLE consistent (public issue 276). * Clarify render pass compatibility in different usage scenarios (public issues 303 and 304). * Add valid usage statements to slink:VkFramebufferCreateInfo requiring that the width, height, and number of layers of the framebuffer all be nonzero (public issue 432). * Allow `offset` and `align` in any GLSL version for the `GL_KHR_vulkan_glsl` extension (public issue 435). * Specify lifetime of string objects passed to the tlink:PFN_vkDebugReportCallbackEXT user callback in the +VK_EXT_debug_report+ extension (public issue 446). * Fix inter-page links in multi-file reference pages (public issue 454). Internal Issues: * Update valid usage language for slink:VkImageCreateInfo to disallow creating images that have ename:VK_IMAGE_USAGE_TRANSIENT_ATTACHMENT_BIT set without other attachment usage bits (ename:VK_IMAGE_USAGE_INPUT_ATTACHMENT_BIT, ename:VK_IMAGE_USAGE_COLOR_ATTACHMENT_BIT, or ename:VK_IMAGE_USAGE_DEPTH_STENCIL_ATTACHMENT_BIT) (internal issue 540). * Disable `VK_EXT_swapchain_colorspace` extension until internal issues 640 and 661 are mutually resolved. * Allow alternative mipmap level selection when [eq]#lambda == 0.5# during texture <<textures-image-level-selection,Image Level(s) Selection>> (internal issue 680). Other Issues: * Add a clarification to the style guide that the extension revision number is treated as a patch number, so that changes to published extensions should only include bug fixes and spec clarifications.
2017-02-17 11:57:46 +00:00
link = ''
if parent.document.attributes['cross-file-links']
link = '<code><a href="' + target + '.html">' + target + '</a></code>'
else
link = '<code><a href="#' + target + '">' + target + '</a></code>'
end
link
Change log for February 10, 2017 Vulkan 1.0.40 spec update: * 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.
2017-02-11 04:37:39 +00:00
end
end
class CodeInlineMacroBase < VulkanInlineMacroBase
def process parent, target, attributes
'<code>' + target + '</code>'
end
end
class StrongInlineMacroBase < VulkanInlineMacroBase
def process parent, target, attributes
'<code>' + target + '</code>'
end
end
class ParamInlineMacroBase < VulkanInlineMacroBase
def process parent, target, attributes
'<code>' + target + '</code>'
end
end
class CanInlineMacro < NormativeInlineMacroBase
named :can
match /can:(\w*)/
def text
'can'
end
end
class CannotInlineMacro < NormativeInlineMacroBase
named :cannot
match /cannot:(\w*)/
def text
'cannot'
end
end
class MayInlineMacro < NormativeInlineMacroBase
named :may
match /may:(\w*)/
def text
'may'
end
end
class MayNotInlineMacro < NormativeInlineMacroBase
named :maynot
match /maynot:(\w*)/
def text
'may not'
end
end
class MustInlineMacro < NormativeInlineMacroBase
named :must
match /must:(\w*)/
def text
'must'
end
end
class MustNotInlineMacro < NormativeInlineMacroBase
named :mustnot
match /mustnot:(\w*)/
def text
'must not'
end
end
class OptionalInlineMacro < NormativeInlineMacroBase
named :optional
match /optional:(\w*)/
def text
'optional'
end
end
class RecommendInlineMacro < NormativeInlineMacroBase
named :recommend
match /recommend:(\w*)/
def text
'recommend'
end
end
class RequiredInlineMacro < NormativeInlineMacroBase
named :required
match /required:(\w*)/
def text
'required'
end
end
class ShouldInlineMacro < NormativeInlineMacroBase
named :should
match /should:(\w*)/
def text
'should'
end
end
class ShouldNotInlineMacro < NormativeInlineMacroBase
named :shouldnot
match /shouldnot:(\w*)/
def text
'should not'
end
end
class FlinkInlineMacro < LinkInlineMacroBase
named :flink
match /flink:(\w+)/
end
class FnameInlineMacro < StrongInlineMacroBase
named :fname
match /fname:(\w+)/
end
class FtextInlineMacro < StrongInlineMacroBase
named :ftext
match /ftext:(\w+)/
end
class SnameInlineMacro < CodeInlineMacroBase
named :sname
match /sname:(\w+)/
end
class SlinkInlineMacro < LinkInlineMacroBase
named :slink
match /slink:(\w+)/
end
class StextInlineMacro < CodeInlineMacroBase
named :stext
match /stext:(\w+)/
end
class EnameInlineMacro < CodeInlineMacroBase
named :ename
match /ename:(\w+)/
end
class ElinkInlineMacro < LinkInlineMacroBase
named :elink
match /elink:(\w+)/
end
class EtextInlineMacro < CodeInlineMacroBase
named :etext
match /etext:([\w\*]+)/
end
class PnameInlineMacro < ParamInlineMacroBase
named :pname
match /pname:((\w[\w.]*)*\w+)/
end
class PtextInlineMacro < ParamInlineMacroBase
named :ptext
match /ptext:((\w[\w.]*)*\w+)/
end
class DnameInlineMacro < CodeInlineMacroBase
named :dname
match /dname:(\w+)/
end
class DlinkInlineMacro < LinkInlineMacroBase
named :dlink
match /dlink:(\w+)/
end
class TnameInlineMacro < CodeInlineMacroBase
named :tname
match /tname:(\w+)/
end
class TlinkInlineMacro < LinkInlineMacroBase
named :tlink
match /tlink:(\w+)/
end
class BasetypeInlineMacro < CodeInlineMacroBase
named :basetype
match /basetype:(\w+)/
end
class CodeInlineMacro < StrongInlineMacroBase
named :code
match /code:(\w+)/
end