1// Copyright 2015-2021 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5[[miscellaneous]] 6= Image Authoring, Formats, and Style 7 8Images used in the Vulkan documents must be kept in the directory `images/` 9in SVG format. 10 11Images should be authored in the open-source 12link:https://inkscape.org/[`Inkscape`] tool, downloadable from its website 13or packaged as an optional install for most Linux distributions. 14This allows other people to easily edit your images in the future. 15Also, while SVG is in principle a portable image format, some proprietary 16image editors have been observed to produce images incompatible with the PDF 17image pipeline used by the Specification. 18 19Images must be authored at their actual image size in the HTML and PDF 20output documents, and must not be scaled with asciidoctor options. 21In most cases, images are included as standalone figures and should occupy 22the full width of the document - do not leave unnecessary whitespace on 23either side of the image. 24 25The PDF output has an available width of just over 660px (at the default 2696dpi), and a height somewhere around 1000px (which diagrams should really 27go nowhere near anyway). 28The html output is wider (800 pixels) and with practically unlimited height. 29As the PDF dimensions are more restrictive, images should not exceed these 30limits. 31 32[NOTE] 33.Note 34==== 35According to the documentation available, the PDF output *should* have 36dimensions of roughly 184mm x 271mm - or equivalently 697px x 1026px (A4 37size [asciidoctor default] with a 0.5in margin [prawn-pdf default] on each 38side). 39However for reasons currently unknown, at least the available width before 40images are scaled down lies is about 30-something pixels lower than that; 41the height where this happens has not been measured, but is likely to 42similarly be lower than it should be for reasons currently unknown. 43==== 44 45Dimensions of elements in the SVG file should be authored in pixels (`px`) 46such that lines/strokes are not unnecessarily anti-aliased (e.g. usually 47stick to integer pixel widths for lines). 48In many cases it is useful to also set the background grid to px, but it not 49necessary; Inkscape has reliable conversions between px and mm using a 50default dpi of 96 (which matches the PDF output), so the output dimension is 51mostly irrelevant. 52 53Text in images should usually appear at 12 point type so as to match that in 54the body of the specification, though 10 point text can be used sparingly 55where necessary (however this is often indicative of the diagram being too 56cramped, so authors should consider scaling or reworking the diagram 57instead). 58Text should use the built-in generic sans serif font so as to ensure the 59font in the output document matches whatever sans serif font is used for 60that document. 61Note that the character set is currently <<character-sets-in-svg,restricted 62to Windows-1252>>. 63 64The font and color scheme used for existing images (black, red, and 50% 65gray) should be used for changes and new images whenever reasonable to do 66so, to preserve a consistent look and feel. 67Whilst a white background is typically assumed, explicitly adding white as a 68color should be avoided - instead leave elements transparent so the diagrams 69can be used in other documents. 70 71Many other elements are consistent throughout the set of diagrams which 72should be maintained in new diagrams where possible. 73Examples include: 74 75 * Lines are usually either fully solid, or use a consistent, and 76 relatively spacious, dash style. 77 * Lines are capped with a consistent arrow shape where relevant. 78 * Small solid circles representing points are a consistently sized circle. 79 80Whenever reasonable, it is advised to copy an existing similar diagram and 81edit it rather than creating one from scratch in order to re-use elements 82and maintain consistency. 83 84 85[[character-sets-in-svg]] 86== Character sets in SVG files 87 88At the moment, the PDF conversion path only supports the Windows-1252 89character set, as we are currently using the standard fonts built into every 90PDF viewer - such that we do not have to embed a different font. 91Unfortunately these only support Windows-1252, which is a highly limited 92character set. 93 94As such, characters not in that set will not display properly when present 95in an SVG, and will fire a warning when building the PDF. 96Luckily, Inkscape has an "Object to path" function built in, which will 97convert text to a raw path, allowing these characters to be supported. 98 99Please ensure that you build the PDF before submitting any new images, 100particularly with non-standard characters, in order to catch such errors. 101 102 103ifdef::editing-notes[] 104[NOTE] 105.editing-note 106==== 107*Other Stuff Which May Be Described In This Chapter Eventually* 108 109 * Something about Image formats 110 * Something about validation scripts 111 * Glossary lists 112 * New param/enum macros 113==== 114endif::editing-notes[] 115 116