Creare immagini e video per la documentazione

Throughout the documentation, images are often needed to make the explanation of a feature or concept as clear as possible for a reader. This page will explain the process from beginning to end.

Immagini

Catturare un immagine

Per catturare una foto di qualcosa in Godot, è possibile utilizzare uno strumento di cattura dello schermo.

Su Windows 10 e 11 questo sarebbe il programma Snip & Sketch. Premendo Windows + Maiusc + S è possibile catturare uno screenshot di una porzione dello schermo e salvarlo negli appunti. Dopo aver premuto questi tasti, cliccare e trascinare sull'area di cui si desidera catturare l'immagine.

On macOS, pressing Shift + Command + 3 does the same. To take a picture of the entire screen press Shift + Command + 4. All screenshots taken will be saved to the desktop.

Each Linux desktop environment has it's own screenshot tool. For example, on KDE Plasma the program Spectacle is used for taking screenshots. If your distribution doesn't come with one by default try searching its package repository, or Flathub if that's supported.

All screenshots should ideally be taken on a 1080p screen. Anything higher resolution is adding detail that doesn't make the documentation better and dramatically increases file size. If you're taking screenshots on a higher resolution screen the screenshot should be scaled down. There are instructions on how to do this later on this page.

Conversione di formato

The current format for images in Godot's documentation is WebP (.webp). While some Linux programs will support saving screenshots in this format, macOS and the Snip & Sketch program on Windows do not. For images that don't need editing, such as precise cropping or adding outlines, Squoosh can be used. Squoosh is a converter developed by Google, is open source, and doesn't give Google any image rights by using it. When choosing compression if you can get an image that's under 300KB in size use lossless compression. If it's over 300KB, use just enough lossy compression to get it under that size. If this results in noticeable compression artifacts using less compression is fine, even if the file size is bigger.

If you already have an image editor such as GIMP, Krita or Photoshop installed it may have the ability to open an image then save it as a WebP file.

Nota

Since WebP supports animations and the documentation can display videos, GIFs should be avoided. Their compression is inefficient and they only support a 256-color palette with 1-bit transparency.

Ritagliare

For a screenshot of a 2D or 3D scene in the editor, the above steps will be enough. But for most UI images some extra work should be done, specifically cropping to make an image look clean. Below is an example of good cropping.

For cropping Krita is the recommended program. While some screenshot programs do have cropping built-in it's not always easy to get something precise. And while Krita is designed as a painting program the cropping tool gives you pixel precision by default. Of course, feel free to use a different program you are familiar with.

If you've never used Krita before download it from the official Krita website, on Linux you may also be able to download it from your distributions repository, flathub is also an option. Once it's installed on your computer open Krita then open the image you want to crop. This button on the left panel is the crop tool.

After selecting it, click on the image, you should now have cropping tools available.

Click and drag the white boxes to adjust what gets cropped, if you zoom in close to the image you will see the individual pixels in an image, which is useful for precision.

If you make a mistake and overcrop don't worry, cropping is non-destructive in Krita and can be adjusted. Click on the image with your cropping tool still selected and the controls will return.

Rimpicciolire un immagine

Come spiegato in precedenza in questa pagina, tutte le immagini catturate su uno schermo con una risoluzione superiore a 1080p si devono ridimensionare. Per farlo in Krita, cliccare su Image nella barra in alto e dal menu a tendina selezionare Scale Image To New Size. Questo menu si può aprire anche premendo Ctrl + Alt + I. In questo menu si possono aggiustare le dimensioni in pixel. Per qualsiasi immagine catturata su un monitor 4K, modificare i valori di larghezza e altezza a metà del loro valore attuale; per qualsiasi immagine catturata su un monitor 1440p, moltiplicare larghezza e altezza per 0,75. Assicurarsi che la casella Constrain Proportions in fondo al menu sia spuntata, così da dover cambiare solo 1 valore.

Salvare come WebP in Krita

Per salvare un'immagine come webp, se non lo è già, andare su File > Save As. Selezionare webp dal menu a discesa Save as type:, quindi scegliere dove salvarla. Dopo aver cliccato su Save, apparirà un menu con le opzioni per webp. Assicurarsi che Lossless sia selezionato e che Quality sia impostata al 100%. Ciò assicura che l'immagine non perderà dettagli e sarà il più piccola possibile.

Se l'immagine supera i 300 KB, provare a comprimerla lossdi dati tramite Squoosh. Se supera ancora i 300 KB, passa alla compressione con perdita di dati e aumentala gradualmente fino a scendere sotto i 300 KB. Se questo causa artefatti di compressione evidenti, utilizzare meno compressione va bene, anche se le dimensioni del file sono più grandi.

Contorni, frecce e testo

A volte un'immagine ha bisogno di qualcosa in più per attirare l'attenzione del lettore o chiarire un concetto. Contorni e frecce si possono utilizzare a questo scopo. Per questo tipo di modifiche, Inkscape è il programma open source consigliato, scaricabile dal sito web ufficiale di Inkscape. Come per Krita, se si utilizza Linux è anche possibile consultare il repository della propria distribuzione o scaricarlo da Flathub.

In questo articolo non viene fornito un tutorial completo sulla creazione di contorni; consigliamo di cercare online diversi tutorial su come utilizzarli. Tuttavia, esistono due standard per i contorni e le frecce delle immagini dei documenti. Innanzitutto, il colore dovrebbe essere giallo, in particolare questo colore esadecimale: fffb44 (fffb44ff se è presente un valore di trasparenza come in Inkscape). Questo colore è stato scelto apposta, per garantire che le persone daltoniche non abbiano difficoltà a leggere la documentazione. Oltre al giallo, è possibile utilizzare altri colori se sono necessari più contorni su un'immagine. Il rosso è invece da evitare. Il secondo standard prevede che tutti i contorni e le frecce debbano avere una larghezza di 2 pixel.

Finally, some images might require text to differentiate multiple parts of an image. There are no strict requirements other than use an easy to read non fancy font. As for color the yellow color from before should also be used, but black or other colors can be used if appropriate. For example, if yellow blends into the image, or if there are multiple outlines in multiple colors.

Aggiungere un immagine a una pagina di documentazione

Una volta finito di lavorare sull'immagine, si può aggiungere alla documentazione. Tutte le immagini sono archiviate in cartelle denominate img accanto alla pagina in cui sono utilizzate.

Per aggiungere l'immagine, inserirla nella cartella img, che si trova nella stessa cartella del file .rst per la pagina (da creare se non esiste). Nella pagina .rst, le immagini si devono includere con il seguente frammento di codice:

.. image:: img/documentation_image.webp

Dove documentation_image.webp sarebbe cambiato con il nome dell'immagine creata. Assegnare alle immagini un nome che ne renda chiaro il significato, possibilmente con un prefisso che ne renda esplicita la relazione con una pagina di documentazione.

Video

Catturare un video

Per registrare un video di qualcosa in Godot, è possibile utilizzare uno strumento di cattura dello schermo. I sistemi operativi generalmente non sono dotati di strumenti flessibili abbastanza per questo, quindi è necessario installare un'utilità di terze parti.

OBS Studio è la scelta più popolare, ma SimpleScreenRecorder si può utilizzare come alternativa su Linux. ShareX si può utilizzare come alternativa su Windows. Tutti questi strumenti si possono configurare per registrare l'intero schermo, una finestra specifica o un rettangolo predeterminato.

Il frame rate consigliato per le registrazioni video è di 60 FPS, ma è possibile utilizzare 30 FPS per video più lunghi, riducendone le dimensioni. Per i video a schermo intero, utilizzare una risoluzione di 1280×720.

Nota

La modalità Movie Maker di Godot si può utilizzare per registrare il risultato di un progetto in esecuzione, incluso l'audio. Non richiede l'installazione di software di terze parti ed evita perdite di fotogrammi (anche quando si registra su un dispositivo lento), ma è meno flessibile.

Comprimere il video catturato

Si consiglia di registrare il video alla massima qualità possibile (senza perdere fotogrammi a causa dell'eccessivo utilizzo della CPU/GPU), per poi ricodificarlo in un secondo momento per ridurne le dimensioni. Questo risulta in una compressione più efficiente rispetto a ridurre direttamente le dimensioni del file, poiché i metodi di compressione in tempo reale sono meno efficienti rispetto ai metodi di compressione più lenti.

Per ricodificare i video e ottenere file di dimensioni inferiori, utilizzare HandBrake o la riga di comando FFmpeg <https://ffmpeg.org/> come segue:

ffmpeg -i input.mp4 -crf 23 output.webm

Il numero dopo -crf regola la qualità del video: numeri più alti risultano in una qualità inferiore (e file di dimensioni inferiori). Un CRF di 23 è un buon punto di partenza, ma potrebbe essere necessario utilizzare un valore più alto per i video più lunghi, affinché le dimensioni del file rimangano ragionevoli. Se possibile, cercare di ottenere file di dimensioni inferiori a 2 MB.

If the video was recorded in a higher resolution or framerate, you can adjust its output resolution and framerate as follows:

ffmpeg -i input.mp4 -crf 23 -vf scale=1280:-2 -r 30 output.webm

This results in a video resolution around 1280×720 at 30 FPS. The exact video resolution will vary depending on the source's aspect ratio.

Suggerimento

If the video was recorded with an audio track but this audio track is not necessary, consider stripping it by adding the -an option to the FFmpeg command line (before the output file name). This will reduce file size and also ensure audio controls don't show up on the video when played in a browser.

Aggiungere un video a una pagina di documentazione

Once you've finished working on your video, it can be added to the documentation. All videos are stored in folders named video next to the page they are used in.

To add your video, add it to the video folder that's in the same folder as the .rst file for the page (create it if it doesn't exist). In the .rst page, videos should be included with the following code snippet:

.. video:: video/csg_tools.webm
   :alt: Put a text description of the video here
   :autoplay:
   :loop:
   :muted:
   :align: default

Where documentation_video.webp would be changed to the name of the video you created. Name your videos in a way that makes their meaning clear, possibly with a prefix that makes their relationship to a documentation page explicit.

The :autoplay:, :loop: and :muted: flags should always be specified unless the video needs to play audio. In this case, do not specify any of these flags. The :align: default flag should always be specified.