mirror of
https://github.com/status-im/Vulkan-Docs.git
synced 2025-02-28 14:00:27 +00:00
Update README
- make sentence a list for lesser cognitive strain - add references to Vulkan-Headers repo - add reference to Vulkan-Ecosystem repo - separate obsolete and irrelevant info from the basic info - update directory tree - add\convert to links (for easier navigation) - lots of frivolous changes
This commit is contained in:
Petr Kraus
parent
8d6a7b23a7
commit
4bea57364f
105
README.adoc
105
README.adoc
@ -1,69 +1,94 @@
|
|||||||
|
ifdef::env-github[]
|
||||||
|
:note-caption: :information_source:
|
||||||
|
endif::[]
|
||||||
|
|
||||||
= Vulkan^(R)^ API Documentation Project
|
= Vulkan^(R)^ API Documentation Project
|
||||||
|
|
||||||
This repository contains formal documentation of the Vulkan API. This
|
This repository contains sources for the formal documentation of the Vulkan
|
||||||
includes the Specification of the Vulkan API, including extensions; the
|
API. This includes:
|
||||||
reference ("`man`") pages; the XML API Registry; header files; and related
|
|
||||||
tools and scripts.
|
[options="compact"]
|
||||||
|
* the Vulkan API Specification
|
||||||
|
* specification of Vulkan Extensions
|
||||||
|
* the reference ("`man`") pages
|
||||||
|
* the XML API Registry (also mirrored at
|
||||||
|
https://github.com/KhronosGroup/Vulkan-Headers)
|
||||||
|
* Vulkan header files (also mirrored at
|
||||||
|
https://github.com/KhronosGroup/Vulkan-Headers)
|
||||||
|
* related tools and scripts.
|
||||||
|
|
||||||
The authoritative public repository is located at
|
The authoritative public repository is located at
|
||||||
https://github.com/KhronosGroup/Vulkan-Docs/ . Issues, proposed fixes for
|
https://github.com/KhronosGroup/Vulkan-Docs/.
|
||||||
issues, and other suggested changes should be created using Github.
|
It hosts public Issue tracker, and accepts patches (Pull Requests) from the
|
||||||
|
general public.
|
||||||
|
|
||||||
|
If in doubt where to submit your Issue consult the
|
||||||
|
https://github.com/KhronosGroup/Vulkan-Ecosystem repo.
|
||||||
|
|
||||||
|
|
||||||
== Branch Structure
|
== Branch Structure
|
||||||
|
|
||||||
With the release of Vulkan 1.1, the current Specification is now maintained
|
Everything is now maintained in the `master` branch of the repository.
|
||||||
in the `master` branch of the repository. It is possible to generate both
|
From this branch it is possible to generate both Vulkan 1.1 and Vulkan 1.0
|
||||||
Vulkan 1.1 and Vulkan 1.0 Specifications from this branch.
|
Specifications, as well as specifications for any set of Extensions.
|
||||||
|
|
||||||
|
[NOTE]
|
||||||
=== `1.0` Branch Is Obsolete
|
====
|
||||||
|
Old revisions of the repository maintained the Vulkan 1.0 Specification in
|
||||||
The `1.0` branch in which the 1.0 Specification was previously maintained is
|
the `1.0` branch, and extensions in the `1.0-VK_EXTENSION_NAME`.
|
||||||
now obsolete. The `1.0` branch will not be updated going forward, and all
|
These branches are now **obsolete**, and contain only very old versions of
|
||||||
outstanding pull requests or merge requests against the `1.0` branch must be
|
the Specification (and extensions).
|
||||||
rebased on, and retargeted to `master`.
|
====
|
||||||
|
|
||||||
|
|
||||||
== Directory Structure
|
== Directory Structure
|
||||||
|
|
||||||
The directory structure was changed following the 1.1.70 spec update to move
|
The directory structure is as follows:
|
||||||
the specification directory to the root of the repository, and move other
|
|
||||||
content relative to that. There may be additional cleanup and simplification
|
|
||||||
in the future.
|
|
||||||
|
|
||||||
|
|
||||||
```
|
```
|
||||||
README.adoc This file
|
README.adoc This file
|
||||||
BUILD.adoc Build targets and methods for the specification
|
BUILD.adoc Documents how to build the specifications, and man pages
|
||||||
ChangeLog.txt Change log summary for each public spec update
|
COPYING.md Copyright and licensing information
|
||||||
appendices/ Specification appendices
|
CODE_OF_CONDUCT.md Code of Conduct
|
||||||
chapters/ Specification chapters
|
ChangeLog.txt Change log summary for each public spec update
|
||||||
config/ asciidoc configuration
|
Makefile, make* Makefile and helper build scripts (see BUILD.adoc)
|
||||||
images/ Images (figures, diagrams, icons)
|
appendices/ Specification appendices
|
||||||
include/vulkan/ Vulkan headers, generated from the Registry
|
chapters/ Specification chapters
|
||||||
man/ Reference (manual) pages for API, mostly extracted from the spec source
|
config/ Asciidoctor configuration
|
||||||
xml/ XML API Registry (vk.xml) and related scripts
|
images/ Images (figures, diagrams, icons)
|
||||||
src/ext_loader/ Extension loader library
|
include/vulkan/ Vulkan headers, generated from the Registry
|
||||||
|
man/ Reference (man) pages for the API; mostly extracted from the spec source
|
||||||
|
out/ Default directory for the generated documents
|
||||||
|
scripts/ Related scripts (but many scripts are still in the root or xml/ directory)
|
||||||
|
src/ext_loader/ Extension loader library (deprecated)
|
||||||
|
style/ Sources for "styleguide" (Vulkan Documentation and Extensions: Procedures and Conventions)
|
||||||
|
xml/ XML API Registry (vk.xml) and related scripts
|
||||||
|
registry.txt Sources for documentation of the vk.xml format
|
||||||
```
|
```
|
||||||
|
|
||||||
|
This structure was adopted following 1.1.70 spec update.
|
||||||
|
There may be additional cleanup and simplification in the future.
|
||||||
|
|
||||||
|
|
||||||
== Building the Specification and Reference Pages
|
== Building the Specification and Reference Pages
|
||||||
|
|
||||||
The document sources are marked up in `asciidoctor` format, and we use
|
The document sources are marked up in Asciidoctor format, and we use
|
||||||
asciidoctor and related toolchain components to generate output documents.
|
`asciidoctor` and related toolchain components to generate output documents.
|
||||||
See `BUILD.adoc` for more information on installing the toolchain and
|
See link:BUILD.adoc[BUILD.adoc] for more information on installing the
|
||||||
building the Specification.
|
toolchain and building the Specification.
|
||||||
|
|
||||||
|
|
||||||
== Generating Headers and Related Files
|
== Generating Headers and Related Files
|
||||||
|
|
||||||
|
See link:xml/README.adoc[xml/README.adoc].
|
||||||
|
|
||||||
The header files (`include/vulkan/vulkan*.h`) and many parts of the
|
The header files (`include/vulkan/vulkan*.h`) and many parts of the
|
||||||
specification and reference page documents are generated from descriptions
|
specification and reference page documents are generated from descriptions
|
||||||
in the XML API Registry (`xml/vk.xml`). The generated files, with the
|
in the XML API Registry (`xml/vk.xml`).
|
||||||
exception of header files, are not checked into the repository. If you
|
The generated files (with the exception of header files) are not checked
|
||||||
change `vk.xml`, you can regenerate the header by going to `xml/` and
|
into the repository.
|
||||||
running:
|
If you change `vk.xml`, you can regenerate the header by going into `xml/`
|
||||||
|
and running:
|
||||||
|
|
||||||
$ make clean install
|
$ make clean install
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user