xref: /third_party/vk-gl-cts/external/vulkan-docs/src/style/misc.adoc

// Copyright 2015-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

[[miscellaneous]]
= Image Authoring, Formats, and Style

Images used in the Vulkan documents must be kept in the directory `images/`
in SVG format.

Images should be authored in the open-source
link:https://inkscape.org/[`Inkscape`] tool, downloadable from its website
or packaged as an optional install for most Linux distributions.
This allows other people to easily edit your images in the future.
Also, while SVG is in principle a portable image format, some proprietary
image editors have been observed to produce images incompatible with the PDF
image pipeline used by the Specification.

Images must be authored at their actual image size in the HTML and PDF
output documents, and must not be scaled with asciidoctor options.
In most cases, images are included as standalone figures and should occupy
the full width of the document - do not leave unnecessary whitespace on
either side of the image.

The PDF output has an available width of just over 660px (at the default
96dpi), and a height somewhere around 1000px (which diagrams should really
go nowhere near anyway).
The html output is wider (800 pixels) and with practically unlimited height.
As the PDF dimensions are more restrictive, images should not exceed these
limits.

[NOTE]
.Note
====
According to the documentation available, the PDF output *should* have
dimensions of roughly 184mm x 271mm - or equivalently 697px x 1026px (A4
size [asciidoctor default] with a 0.5in margin [prawn-pdf default] on each
side).
However for reasons currently unknown, at least the available width before
images are scaled down lies is about 30-something pixels lower than that;
the height where this happens has not been measured, but is likely to
similarly be lower than it should be for reasons currently unknown.
====

Dimensions of elements in the SVG file should be authored in pixels (`px`)
such that lines/strokes are not unnecessarily anti-aliased (e.g. usually
stick to integer pixel widths for lines).
In many cases it is useful to also set the background grid to px, but it not
necessary; Inkscape has reliable conversions between px and mm using a
default dpi of 96 (which matches the PDF output), so the output dimension is
mostly irrelevant.

Text in images should usually appear at 12 point type so as to match that in
the body of the specification, though 10 point text can be used sparingly
where necessary (however this is often indicative of the diagram being too
cramped, so authors should consider scaling or reworking the diagram
instead).
Text should use the built-in generic sans serif font so as to ensure the
font in the output document matches whatever sans serif font is used for
that document.
Note that the character set is currently <<character-sets-in-svg,restricted
to Windows-1252>>.

The font and color scheme used for existing images (black, red, and 50%
gray) should be used for changes and new images whenever reasonable to do
so, to preserve a consistent look and feel.
Whilst a white background is typically assumed, explicitly adding white as a
color should be avoided - instead leave elements transparent so the diagrams
can be used in other documents.

Many other elements are consistent throughout the set of diagrams which
should be maintained in new diagrams where possible.
Examples include:

  * Lines are usually either fully solid, or use a consistent, and
    relatively spacious, dash style.
  * Lines are capped with a consistent arrow shape where relevant.
  * Small solid circles representing points are a consistently sized circle.

Whenever reasonable, it is advised to copy an existing similar diagram and
edit it rather than creating one from scratch in order to reuse elements and
maintain consistency.


[[character-sets-in-svg]]
== Character Sets in SVG Files

At the moment, the PDF conversion path only supports the Windows-1252
character set, as we are currently using the standard fonts built into every
PDF viewer - such that we do not have to embed a different font.
Unfortunately these only support Windows-1252, which is a highly limited
character set.

As such, characters not in that set will not display properly when present
in an SVG, and will generate a warning when building the PDF.
Luckily, Inkscape has an "`Object to path`" function built in, which will
convert text to a raw path, allowing these characters to be supported.

Please ensure that you build the PDF before submitting any new images,
particularly with non-standard characters, in order to catch such errors.


ifdef::editing-notes[]
[NOTE]
.editing-note
====
*Other Stuff Which May Be Described In This Chapter Eventually*

  * Something about Image formats
  * Something about validation scripts
  * Glossary lists
  * New param/enum macros
====
endif::editing-notes[]