codegen/vulkan/vulkan-docs-next/style/misc.adoc - platform/hardware/google/gfxstream - Git at Google

 // Copyright 2015-2023 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[]
	// Copyright 2015-2023 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[]