docs_image_guidelines.rst 7.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153
  1. .. _docs_image_guidelines:
  2. Creating documentation images
  3. =============================
  4. Throughout documentation images are often needed to make the explanation
  5. of a feature or concept as clear as possible for a reader. This page will
  6. explain the process from beginning to end.
  7. Capturing an image
  8. ------------------
  9. To take a picture of something in Godot a screen capture tool can be used.
  10. On Windows 10 and 11 that would be the Snip & Sketch program.
  11. Pressing :kbd:`Windows + Shift + S` lets you take a screenshot
  12. of a portion of the screen and save it to the clipboard.
  13. After pressing those keys, click and drag over
  14. the area you wish to take a picture of.
  15. On macOS, pressing :kbd:`Shift + Command + 3` does the same.
  16. To take a picture of the entire screen press :kbd:`Shift + Command + 4`.
  17. All screenshots taken will be saved to the desktop.
  18. Each Linux desktop environment has it's own screenshot tool. For example,
  19. on KDE Plasma the program Spectacle is used for taking screenshots. If your
  20. distribution doesn't come with one by default try searching its package
  21. repository, or Flathub if that's supported.
  22. All screenshots should ideally be taken on a 1080p screen. Anything higher
  23. resolution is adding detail that doesn't make the documentation better and
  24. dramatically increases file size. If you're taking screenshots on a higher
  25. resolution screen the screenshot should be scaled down. There are instructions
  26. on how to do this later on this page.
  27. Format conversion
  28. -----------------
  29. The current format for images in Godot's documentation is WebP (``.webp``).
  30. While some Linux programs will support saving screenshots in this format, macOS
  31. and the Snip & Sketch program on Windows do not. For images that don't need
  32. editing, such as precise cropping or adding outlines, Squoosh can be used.
  33. `Squoosh <https://squoosh.app/>`_ is a converter developed by Google, is open
  34. source, and doesn't give Google any image rights by using it. When choosing
  35. compression if you can get an image that's under 300KB in size use lossless
  36. compression. If it's over 300KB use just enough lossy compression to get it
  37. under that size. If this results in noticable compression artifacts using less
  38. compression is fine, even if the file size is bigger.
  39. If you already have an image editor such as GIMP, Krita or Photoshop installed
  40. it may have the ability to open an image then save it as a WebP file.
  41. Cropping
  42. --------
  43. For a screenshot of a 2D or 3D scene in the editor the above steps will be enough.
  44. But for most UI images some extra work should be done, specifically cropping to
  45. make an image look clean. Below is an example of good cropping.
  46. .. image:: img/cropped_image.webp
  47. For cropping Krita is the recommended program. While some screenshot programs do
  48. have cropping built in it's not always easy to get something precise. And while
  49. Krita is designed as a painting program the cropping tool gives you pixel precision
  50. by default. Of course, feel free to use a different program you are familiar with.
  51. If you've never used Krita before download it from the `official Krita website <https://krita.org/en/download/krita-desktop/>`_,
  52. on Linux you may also be able to download it from your distributions repository,
  53. flathub is also an option. Once it's installed on your computer open Krita then
  54. open the image you want to crop. This button on the left panel is the crop tool.
  55. .. image:: img/crop_tool.webp
  56. After selecting it, click on the image, you should now have cropping tools available.
  57. .. image:: img/crop_edit.webp
  58. Click and drag the white boxes to adjust what gets cropped, if you zoom in close
  59. to the image you will see the individual pixels in an image, which is useful for
  60. precision.
  61. .. image:: img/crop_pixels.webp
  62. If you make a mistake and overcrop don't worry, cropping is non-destructive in
  63. Krita and can be adjusted. Click on the image with your cropping tool still selected
  64. and the controls will return.
  65. Scaling down an image
  66. ---------------------
  67. As explained earlier on this page, all images taken on a screen that is a higher resolution
  68. than 1080p should be scaled down. To do this in Krita click on **Image** on the top bar, and
  69. from the dropdown menu select **Scale Image To New Size**. This menu can also be opened by
  70. pressing :kbd:`Ctrl + Alt + I`. On this menu you want to adjust the pixel dimensions. For
  71. anything taken on a 4K monitor change the value of the width and height to half of its current
  72. value, for anything taken on a 1440p monitor multiply the width and height by 0.75. Make
  73. sure the **Constrain Proportions** box at the bottom of the menu is checked so you only have
  74. to change 1 value.
  75. Saving as WebP in Krita
  76. -----------------------
  77. To save an image as webp if it isn't already one, Go to **File > Save As**. Select **webp** from the
  78. **Save as type:** dropdown, then choose wherever you want to save it. After clicking **Save** a menu
  79. will popup with webp options. Make sure **Losses** is checked and **Quality** is set to 100%. This
  80. means the image will not lose detail and will be as small as possible.
  81. If the image is over 300KB in size try compressing it losslessly using `Squoosh <https://squoosh.app/>`_.
  82. If it's still over 300KB change to lossy compression and slowly increase the compression until it's under
  83. 300KB. If this results in noticable compression artifacts using less compression is fine, even if the file
  84. size is bigger.
  85. Outlines arrows and text
  86. ------------------------
  87. Sometimes an image needs something extra to properly direct the readers
  88. attention, or make something clear. Outlines and arrows can be used
  89. for this purpose. For these types of edits Inkscape is the recommended open
  90. source program, it can be downloaded from the `official Inkscape website <https://inkscape.org/>`_.
  91. Like Krita, if you're on Linux you can also check your distributions repository
  92. or get it from Flathub.
  93. A full tutorial on creating outlines is not provided here, we recommend searching
  94. for various tutorials on how to use it online. However there are two standards
  95. for doc image outlines and arrows. First, the color should be yellow, specifically
  96. this hex color: ``fffb44`` (``fffb44ff`` if there is a transparency value like in Inkscape).
  97. This color was chosen specifically to make sure color blind people do not have
  98. issues reading the documentation, other colors can be used in addition to this yellow
  99. if multiple outlines on an image are needed, red should be avoided. The second standard
  100. is that all outlines and arrow lines should be 2 pixels wide.
  101. Finally, some images might require text to differentiate multiple parts of an image.
  102. There are no strict requirements other than use an easy to read non fancy font. As for
  103. color the yellow color from before should also be used, but black or other colors can
  104. be used if appropriate. For example, if yellow blends into the image, or if there are
  105. multiple outlines in multiple colors.
  106. Adding an image to a documentation page
  107. ---------------------------------------
  108. Once you've finished working on your image, it can be added to the documentation.
  109. All images are stored in folders named ``img`` next to the page they are used in.
  110. To add your image, add it to the ``img`` folder that's in the same folder as the
  111. ``.rst`` file for the page (create it if it doesn't exist). In the ``.rst`` page,
  112. images should be included with the following code snippet::
  113. .. image:: img/documentation_image.webp
  114. Where ``documentation_image.webp`` would be changed to the name of the image you
  115. created. Name your images in a way that makes their meaning clear, possibly with
  116. a prefix that makes their relationship to a documentation page explicit.