116 lines
4.8 KiB
Plaintext
116 lines
4.8 KiB
Plaintext
// Copyright (c) 2015-2019 Khronos Group. This work is licensed under a
|
|
// Creative Commons Attribution 4.0 International License; see
|
|
// http://creativecommons.org/licenses/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
|
|
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 - don't 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 hasn't 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 re-use 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 don't 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 fire 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[]
|
|
|