stan220/godot-docs
1
0
Fork 0
mirror of https://github.com/stan220/godot-docs.git synced 2026-09-08 16:28:59 +00:00
Code Issues Packages Projects Releases Wiki Activity

Changed asset importing and workflow documentation. Pending for 3D..

Browse Source
This commit is contained in:
Juan Linietsky
2017-09-19 17:22:04 -03:00
parent 607dd6fdef
commit 5299515508
15 changed files with 258 additions and 812 deletions
Download Patch File Download Diff File Expand all files Collapse all files
img/asset_workflow1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 60 KiB

img/asset_workflow2.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 24 KiB

img/asset_workflow3.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 26 KiB

img/asset_workflow4.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 5.7 KiB

img/asset_workflow5.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 6.9 KiB

img/image_import1.png
BIN
View File
Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 31 KiB

learning/workflow/assets/exporting_images.rst
-66
View File
@@ -1,66 +0,0 @@
.. _doc_exporting_images:
Exporting images
================
It is often desirable to perform an operation on all or a group of
images upon export. Godot provides some tools for this. Examples of
such operations are:
- Converting all images from a lossless format to a lossy one (ie: png
-> WebP) for greater compression.
- Shrinking all images to half the size, to create a low resolution
build for smaller screens.
- Create an atlas for a group of images and crop them, for higher
performance and less memory usage.
Image export options
--------------------
In the "Project Export Settings" dialog, go to the Images tab:
.. image:: /img/exportimages.png
In this dialog the image extensions for conversion can be selected, and
operations can be performed that apply to all images (except those in
groups, see the next section for those):
- **Convert Image Format**: Probably the most useful operation is to
convert to Lossy (WebP) to save disk space. For lossy, a Quality bar
can set the quality/vs size ratio.
- **Shrink**: This allows to shrink all images by a given amount. It's
useful to export a game to half or less resolution for special
devices.
- **Compress Formats**: Allows to select which image extensions to
convert.
On export, Godot will perform the desired operation. The first export
might be really slow, but subsequent exports will be fast, as the
converted images will be cached.
Image group export options
--------------------------
This section is similar to the previous one, except it can operate on a
selected group of images. When a image is in a group, the settings from
the global export options are overridden by the ones from the group. An
image can only be in one group at a time. So if the image is in a group
other than the current one being edited, it will not be selectable.
.. image:: /img/imagegroup.png
Atlas
~~~~~
Grouping images allows a texture atlas to be created. When this mode is
active, a button to preview the resulting atlas becomes available. Make
sure that atlases don't become too big, as some hardware will not
support textures bigger than 2048x2048 pixels. If this happens, just
create another atlas.
The atlas can be useful to speed up drawing of some scenes, as state
changes are minimized when drawing from it (though unlike other
engines, Godot is designed so state changes do not affect it as much).
Textures added to an atlas get cropped (empty spaces around the image
are removed), so this is another reason to use them (save space). If
unsure, though, just leave that option disabled.
learning/workflow/assets/import_process.rst
+58 -130
View File
@@ -3,162 +3,90 @@
Import process
==============
What is it for?
---------------
Importing assets in Godot 3.0+
------------------------------
One of the most difficult things to get right when creating game engines
is managing the import process. That means, getting the assets that artists
make into the game, in a way that functions optimally.
Previously, importing assets in Godot 2.x required manual maintainance
of a separate directory with source assets. Without doing this, it was
impossible to specify how to convert and change import flags for
textures, audios, scenes, etc.
Artists use certain tools and formats, and programmers would rather have
their data in a different format. This is because artists put their
focus on creating assets with the best quality possible, while
programmers have to make sure they actually run at decent speed (or run
at all), use a certain amount of memory, and don't take ages loading
from disk.
In Godot 3.0, we use a more modern approach to importing: Simply drop
your assets (image files, scenes, audios, fonts, etc) directly in the
project folder (copy them manually with your OS file exporer).
Godot will automatically import these files internally
and keep the imported resources hidden in a res://.import folder.
One would think that just writing a converter/importer would be enough,
but this is not all there is to it. The same way programmers iterate
several times over their code, artists keep making changes to their
assets. This generates a bottleneck, because *someone* has to keep
re-importing that artwork, right? And importing assets is often something
that has to be agreed by both parties, as the programmer needs to decide
how the artwork is imported and the artists needs to see how it looks.
This allows changing all the import parameters transparently.
The goal to establishing an import process is that both can agree on how
the rules under which the assets are going to be imported the first
time, and the system will apply those rules automatically each time the
asset is re-imported.
Changing import parameters
--------------------------
Godot does not do the re-import process automatically, though. It gives
the team the option to do it at any time (a red icon on the top right
of the screen, allows the ability to do it at any desired time).
Changing the import parameters of an asset in Godot (again, keep in mind
import parameters are only present in non-native Godot resource types) is
easy. Just select in the filesystem dock the relevant resource:
Does it always work?
--------------------
.. image:: /img/asset_workflow1.png
The aim of the import system is that it works well enough for most
common cases and projects. What is there has been tested and seems to
cover most needs.
And, after adjusting the parameters, just press "Reimport". The parameters
used will be only for this asset and will be used on future reimports.
However, as mentioned before, this is one of the most difficult areas of
writing a game engine. It may happen often (specially on large projects,
ports, or projects with unusual requirement) that what is provided is
not enough. It's easy to say that the engine is open source and that the
programmer should make their own if they don't like what is there, but
that would be making a huge disservice to the users and not the right
attitude. Because of that, we made sure to provide as many tools and
helpers as possible to support a custom import process, for example:
Changing import parameters of several assets at the same time is also
possible. Simply select all of them together in the resources dock and the
exposed parameters will apply to all of them when reimporting.
- Access to the internals of almost all data structures is provided to
the scripting and C++ API, as well as saving and loading in all
supported file formats.
- Some importers (like the 3D asset importer) support scripts to modify
the data being imported.
- Support for creating custom import plugins is also provided, even for
replacing the existing ones.
- If all else fails, Godot supports adding custom resource loaders,
to load data in alternative formats, without intermediate conversion.
Automatic reimport
------------------
Both the import system and the custom tools provided will improve over
time as more use cases are revealed to us.
When the source asset changes, Godot will perform and automatic reimport
of it, applying the preset configured for that specific asset.
Importing assets
----------------
Files generated
-----------------
Source asset location
~~~~~~~~~~~~~~~~~~~~~
Importing will add an extra <asset>.import file, containing the import
configuration. Make sure to commit these to your version control system!
To begin, it is a good idea to define where the original assets created
by the artists (before they are imported) will be located. Normally,
Godot does not mind much about the location, but if the project has
several developers, it is a good idea to understand the simple rule for
it to work for everyone.
.. image:: /img/asset_workflow4.png
First of all, it would be really good for this location to **not** be
inside the project path (where engine.cfg is located, or any
sub-folder). Godot expects regular resources in there, and may consider
many of the files used as source art as regular resources. This would
lead to it bundling all of them when the project is exported, something
which is undesired.
Additionally, extra assets will be presset in the hidden res://.import folder:
Now that it is clear that this location must be outside the project
folder, the rule that Godot uses to reference external assets can be
explained. When an asset is imported, the engine stores a relative path
from the project path to the asset (In windows, this works as long as
they are on the same drive, otherwise an absolute path is stored). This
ensures that the same asset can be re-imported in another computer.
.. image:: /img/asset_workflow5.png
The usual approach to this, when using a VCS such as Git, Mercurial or
Subversion, is to create the project in a subfolder, so both the game's
project files and the source assets can be committed to a same repository.
For example, the repository layout can look like this:
If any of the files present in this folder is erased (or the whole folder), the
asset or asssets will be reimported automatically. As such, Commiting this folder
to the version control system is optional. It can save time on
reimporting time when checking out in another computer, but it takes considerably
more space and transfer time. Pick your poison!
::
Changing import resource type
-----------------------------
source_assets/sfx/explosion.wav
source_assets/sfx/crash.wav
source_assets/fonts/myfont.ttf
source_assets/translation/strings.csv
source_assets/art/niceart.psd
game/project.godot
Some source assets can be imported as different types of resources.
For this, just select the relevant type of resource desired and
press "Reimport":
In the above example, artists, musician, translators, etc. can work in
the source_assets/ folder, then import the assets to the game/ folder.
When the repository is updated, anyone can re-import the assets if they
changed.
.. image:: /img/asset_workflow2.png
Import dialogs
~~~~~~~~~~~~~~
Godot provides for importing several types of assets, all of them can be
accessed from the import dialog:
Changing default import parameters
-----------------------------------
.. image:: /img/import.png
Different types of games might require different defaults.
Changing the defaults per project can be achieved by using the
"Preset.." Menu. Besides some resource types offering presets,
the default setting can be saved and cleared too:
Each of the dialogs shares a similar function, a source file (or several
of them) must be provided, as well as a target destination inside the
project folders. Once imported, Godot saves this information as metadata
in the imported asset itself.
.. image:: /img/asset_workflow3.png
.. image:: /img/importdialogs.png
Simplicity is key!
------------------
More information about each specific type of asset can be found in
specific sections, such as `Importing Textures <import_textures>`__.
This is a very simple workflow which should take very little time to get used to. It also enforces a more
correct way to deal with resources.
Tracking changes and re-importing
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
There are many types of assets available for import, so please continue reading to understand how to work
with all of them!
Godot tracks changes in the source assets constantly. If at least one
asset has been found to be modified (md5 is different than when it was
imported), a small red indicator will appear in the top right corner of
the screen.
.. image:: /img/changes.png
From that moment onward, the user can choose to re-import at any given
time by clicking on the red-icon. When this action is done, a dialog
will pop-up showing which resources can be re-imported (all selected
by default).
Accepting that dialog will immediately re-import the resources and
will update any of them currently in use in the editor (like a
texture, model or audio file).
.. image:: /img/changed.png
Manually re-importing
~~~~~~~~~~~~~~~~~~~~~
The re-import process is automatic, but it may be desired at some point
to change the settings of an already imported file, so it can be
re-imported differently. For this, the Import Settings window is
provided.
.. image:: /img/isettings.png
This screen allows the user to re-open the corresponding import-window
to re-import that asset again, with the ability to change any of the
settings.
.. image:: /img/reimported.png
learning/workflow/assets/importing_audio_samples.rst
+33 -75
View File
@@ -6,100 +6,56 @@ Importing audio samples
Why importing?
--------------
Importing Audio Samples into the game engine is a process that should be
easier than it really is. Most readers are probably thinking "Why not
just copy the wav files to a folder inside the project and be over
with it?"
Raw audio data in general is large and undesired. Godot provides two main
options to import your audio data: WAV and OGG Vorbis.
It's not usually that simple. Most game engines use uncompressed audio
(in memory, at least) for sound effects. The reason for this is because
it's really cheap to play back and resample. Compressed streamed audio
(such as ogg files) takes a large amount of processor to decode so no
more than one or two are streamed simultaneously. However, with sound
effects, one expects a dozen of them to be playing at the same time in
several situations.
Each has different advantages.
* Wav files use raw data or light compression, requre small amount of CPU to play back (hundreds of simultaneous voices in this format are fine), but take up significant space.
* Ogg Vorbis files use a stronger compression that results in much smaller file size, but uses significantly more processor to play back.
Because of this, sound effects are loaded uncompressed into memory, and
here is where the problems begin.
As is usual with graphics, the situation where programmers don't really
know about audio and audio engineers don't know about programming is
also common in the industry. This leads to a scenario where a project
ends up wasting resources unnecessarily.
.. image:: /img/audio_stram_import.png
To be more precise, SFX artists tend to work with audio formats that
give them a lot of room for tweaking the audio with a low noise floor and
minimum aliasing, such as 96kHz, 24 bits. In many cases, they work in
stereo too. Added to that, many times they add effects with an infinite
or really long fadeout, such as reverb, which leads to apparent trailing
silences. Finally, many DAWs also add silence at the beginning when
normalizing to wav.
Here is a comparative chart.
These often result in extremely large files to integration into a game engine
with sound effects taking dozens of megabytes.
+-------------------------------+---------------------+
| Format | 1 Second of Audio |
+===============================+=====================+
| WAV 24 bits, 96 kHz, Stereo | 576kb |
+-------------------------------+---------------------+
| WAV 16 bits, 44 kHz, Mono | 88kb |
+-------------------------------+---------------------+
| WAV 16 bits, IMA-ADPCM, Mono | 22kb |
+-------------------------------+---------------------+
| OGG 128kbps, Stereo | 16kb |
+-------------------------------+---------------------+
| OGG Vorbis 96kbps, Stereo | 12kb |
+-------------------------------+---------------------+
How much does quality matter?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In general, what is recommended, is to use WAV for most sound effects, specially those that are short and repetitive, and OGG for music, voice and long sound effects.
First of all, it is important to know that Godot has an internal reverb
generator. Sound effects can go to four different setups (small, medium
and large room, as well as hall), with different send amounts. This saves
Best Practices
--------------
Godot 3+ has an amazing bus system with built in effects. This saves
SFX artists the need to add reverb to the sound effects, reducing their
size greatly and ensuring correct trimming. Say no to SFX with baked
reverb!
.. image:: /img/reverb.png
Another common problem is that, while it's useful for working inside a
DAW, high bit depths (24 bits) and high sampling rate (96kHz) are
completely unnecessary for use in a game, as there is no `audible
difference <http://www.youtube.com/watch?v=cIQ9IXSUzuM>`__. If
positional sound is going to be used (for 2D and 3D), the panning and
stereo reverb will be provided by the engine, so there is little need
for stereo sound. How does this affect the resource usage? Look at the
following comparison:
+---------------------------+---------------------+--------------+
| Format | 1 Second of Audio | Frame Size |
+===========================+=====================+==============+
| 24 bits, 96 kHz, Stereo | 576kb | 12 |
+---------------------------+---------------------+--------------+
| 16 bits, 44 kHz, Mono | 88kb | 2 |
+---------------------------+---------------------+--------------+
| 16 bits, IMA-ADPCM | 22kb | 1/2 |
+---------------------------+---------------------+--------------+
As seen, for being no audible difference, the 16 bits, 44kHz, mono conversion
takes *6 times less memory* than the 24 bits, 96kHz, Stereo version. The
IMA-ADPCM version (using computationally-light audio compression) takes *24
times less memory* than what was exported from the DAW.
As you can see above, sound effects become huge with reverb added.
Trimming
~~~~~~~~
One last issue that happens often is that the waveform files received
have silences at the beginning and at the end. These are inserted by
One issue that happens often is that the waveform are exported with long
silences at the beginning and at the end. These are inserted by
DAWs when saving to a waveform, increase their size unnecessarily and
add latency to the moment they are played back. Trimming them solves
this, but it takes effort for the SFX artist, as they have to do it in a
separate application. In the worst case, they may not even know the
silences are being added.
add latency to the moment they are played back.
.. image:: /img/trim.png
Importing audio samples
-----------------------
Godot has a simple screen for importing audio samples to the engine. SFX
artists only have to save the wav files to a folder outside the
project, and the import dialog will fix the files for inclusion, as well
as doing it automatically every time they are modified and re-imported.
.. image:: /img/importaudio.png
In this screen, the quality of the audio can be limited to what is
needed, and trimming is done automatically. In addition, several samples
can be loaded and batch-converted, just as textures can.
Importing as WAV with the Trimming option enabled solves
this.
Looping
~~~~~~~
@@ -111,3 +67,5 @@ supported.
As an alternative, the import screen has a "loop" option that enables
looping for the entire sample when importing.
learning/workflow/assets/importing_fonts.rst
-115
View File
@@ -1,115 +0,0 @@
.. _doc_importing_fonts:
Importing fonts
===============
What is a font?
---------------
Fonts in modern operating systems are created as scalable vector
graphics. They are stored as a collection of curves (usually one for
each character), which are independent of the screen resolution, and
stored in standardized file formats, such as TTF (TrueType) or OTF
(OpenType).
Rendering such fonts to bitmaps is a complex process, which employs
different methods to convert curves to pixels depending on context and
target size. Due to this, this rendering process must be done by using
the CPU. Game engines use the GPU to render, and 3D APIs don't really
support the means to do this efficiently, so fonts have to be converted
to a format that is friendly to the GPU when imported to a project.
Converting fonts
----------------
This conversion process consists of rendering a vector font to a given
point size and storing all the resulting characters in a bitmap texture.
The bitmap texture is then used by the GPU to draw a small quad for each
character and form readable strings.
.. image:: /img/bitmapfont.png
The drawback of this process is that fonts must be pre-imported in the
specific sizes that they will use in the project. However, given that
that bitmap fonts compress really well, this is not as bad as it sounds.
Importing a font
----------------
Fonts are imported via the Font import dialog. The dialog will ask for a
font, a size, some options and a target resource file to save.
.. image:: /img/fontimport.png
The dialog is fully dynamic, which means that any change will be
reflected in the font preview window. The user can tweak almost every
parameter and get instant feedback on how the font will look.
Since the resulting font is a bitmap, a few more options were added to
make the imported font look even nicer. These options were added to
please graphic designers, who love putting gradients, outlines and
shadows in fonts, as well as changing all the inter-spaces available :).
These options will be explained in the next section.
Extra spacing
~~~~~~~~~~~~~
It is possible to add more space for:
- **Characters**, the space between them can be varied.
- **"space" character**, so the distance between words is bigger.
- **Top and Bottom margins**, this changes the spacing between lines as
well as the space between the top and bottom lines and the borders.
.. image:: /img/fontspacing.png
Shadows & outline
~~~~~~~~~~~~~~~~~
Fonts can have a shadow. For this, the font is drawn again, below the original,
in a different color, and then blurred with a Gaussian kernel of different
sizes. The resulting shadow can be adjusted with an exponential function
to make it softer or more like an outline. A second shadow is also
provided to create some added effects, like a bump or outline+shadow.
.. image:: /img/shadowoutline.png
Gradients
~~~~~~~~~
Gradients are also another of the visual effects that graphic designers
often use. To show how much we love them, we added those too. Gradients
can be provided as a simple curve between two colors, or a special png
file with a hand drawn gradient.
.. image:: /img/fontgradients.png
Internationalization
--------------------
Colors, shadows and gradients are beautiful, but it's time we get to
serious business. Developing games for Asian markets is a common
practice in today's globalized world and app stores.
Here's when things get tricky with using bitmap fonts. Asian alphabets
(Chinese, Japanese and Korean) contain dozens of thousands of
characters. Generating bitmap fonts with every single of them is pretty
expensive, as the resulting textures are huge. If the font size is small
enough, it can be done without much trouble, but when the fonts become
bigger, we run out of video ram pretty quickly!
To solve this, Godot allows the user to specify a text file (in UTF-8
format) where it expects to find all the characters that will be used in
the project. This seems difficult to provide at first, and more to keep
up to date, but it becomes rather easy when one realizes that the .csv
with the translations can be used as such a source file (see the
:ref:`doc_importing_translations` section). As Godot re-imports assets when
their dependencies change, both the translation and font files will be
updated and re-imported automatically if the translation csv changes.
Another cool trick for using a text file as limit of which characters
can be imported is when using really large fonts. For example, the user
might want to use a super large font, but only to show numbers. For
this, he or she writes a numbers.txt file that contains "1234567890",
and Godot will only limit itself to import data, thus saving a lot of
video memory.
learning/workflow/assets/importing_images.rst
+156
View File
@@ -0,0 +1,156 @@
.. _doc_import_images:
Importing Images
==============
Why importing them?
-------------------
In Godot 3+, image files are no longer native resources and they must be imported.
The reason behind this is the large amount of configuration parameters that
image files can be imported with.
This small tutorial will explain what these parameters are and how to best
make use of them.
Importing Textures
------------------
The default action in Godot is to import images as textures. Textures are stored
in video memory and can't be accessed directly. This is what makes drawing them
efficient.
Import options are vast:
.. image:: /img/image_import1.png
Compression:
-------------
Images are one of the largest assets in a game. To handle them efficiently, they need to be compressed.
Godot offers several compression methods, depending on the use case.
Compress Mode
~~~~~~~~~~~~~
* VRAM Compression: This is the most common copression mode for 3D assets. File on disk is reduced and
video memory usage is also reduced considerably. For 3D, it may present unwanted arctifacts, though.
* Lossless Compression: This is the most common compression for 2D assets. It shows assets without any
kind of arctifacting, and disk compression is decent. It will use considerably more amount of video memory than VRAM, though.
* Lossy Compression: For games with lots of large 2D assets, lossy compression can be a great choice. It has some arctifacting,
but less than VRAM and the file size is almost a tenth of Lossless.
* Uncompressed: Only useful for formats that can't be compressed (like, raw float).
In this table, each of the four options are described together with their
advantages and disadvantages ( |good| = Best, |bad| =Worst ):
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| | Uncompressed | Compress Lossless (PNG) | Compress Lossy (WebP) | Compress VRAM |
+================+========================+===========================+=========================+======================================================+
| Description | Stored as raw pixels | Stored as PNG | Stored as WebP | Stored as S3TC/BC,PVRTC/ETC, depending on platform |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| Size on Disk | |bad| Large | |regular| Small | |good| Very Small | |regular| Small |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| Memory Usage | |bad| Large | |bad| Large | |bad| Large | |good| Small |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| Performance | |regular| Normal | |regular| Normal | |regular| Normal | |good| Fast |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| Quality Loss | |good| None | |good| None | |regular| Slight | |bad| Moderate |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| Load Time | |regular| Normal | |bad| Slow | |bad| Slow | |good| Fast |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
HDR Mode
~~~~~~~~
Godot supports high dynamic range textures (as .HDR or .EXR). These are mostly useful as high dynamic range equirectancular panorama skys (the internet
has plenty of if you look for them), which replace Cubemaps in Godot 2.x. Modern PCs suport the BC6H VRAM format, but there are still plenty that do not.
If you want Godot to ensure full compatibility in for kind of textures, enable the "Force RGBE" option.
Normal Map
~~~~~~~~~~
When using a texture as normal map, only the red and green channels are required. Given regular texture compression algorithms produce arctifacts that don't
look that nice in normal maps, the RGTC compression format is the best fit for this data. Forcing this option to "Enabled" will make Godot import the
image as RGTC compressed. By default, it's set to "Detect" which means that if the texture is ever used as a normal map, it will be changed to "Enabled" and
reimported automatically.
Flags
-----
There are plenty of settings that can be toggled when importing an image as a texture, depending on the use case.
Repeat
~~~~~~
This setting is mosty commonly used in 3D than 2D (thus it's generally disabled in 2D). It makes UV coordinates going beyond the 0,0 - 1,1 range to "loop".
Repeating can optionally be set to mirrored mode.
Filter
~~~~~~
When pixels become larger than the screen pixels, this options enable linear interpolation for them. The result is a smoother (less blocky) texture. This
setting can be commonly used in 2D and 3D, but it's usually disabled when making pixel perfect games.
Mipmaps
-------
When pixels become smaller than the screen, mipmaps kick in. This helps reduce the grainy effect when shrinking the textures. Keep in mind that, in older hardware
(GLES2, mainly mobile), there are some requirements to use mipmaps:
* Texture width and height must be powers of 2
* Repeat must be enabled
Keep in mind the above when making phone games and applications, want to aim for full compatibility, and need mipmaps.
When doing 3D, mipmap should be turned on as this also improves performance (smaller versions of the texture are used for objects further away).
Anisotropic
~~~~~~~~~~~
When textures are near parallel to the view (like floors), this option makes them have more detail by reducing blurryness.
SRGB
~~~~
Godot uses Linear colorspace when rendering 3D. Textures mapped to albedo or detail channels need to have this option turned on in order for colors to look correct.
When set to "Detect" mode, the texture will be marked as SRGB when used in albedo channels.
Process
-------
Some special processes can be applied to images when importe as texture.
Fix Alpha Border
~~~~~~~~~~~~~~~~
This puts pixels of the same surrounding color in transition from transparency to non transparency. It helps mitigate the outline effect when exporting images
from Photoshop and the likes.
.. image:: /img/fixedborder.png
It's a good idea to leave it on by default, unless specific values are needed.
Premultiplied Alpha
~~~~~~~~~~~~~~~~~~~
An alternative to fix darkened borders is to use premultiplied alpha. By enabling this option, the texture will be converted to this format.
Keep in mind that a material will need to be created that uses the PREMULT ALPHA blend mode on canvas items that need it.
HDR as SRGB
~~~~~~~~~~~~
Some few HDR files are broken and contain SRGB color data. It is advised to not use them but, in the worst case, toggling this option on will make them look right.
Detect 3D
---------
This option makes Godot be aware of when a texture (which is imported for 2D as default) is used in 3D. If this happens, setting are changed so the texture flags
are friendlier to 3D (mipmaps, filter and repeat become enabled and compression is changed to VRAM). Texture is also reimported automaticlaly.
learning/workflow/assets/importing_textures.rst
-256
View File
@@ -1,256 +0,0 @@
.. _doc_importing_textures:
Importing textures
==================
Do NOT import them in most cases
--------------------------------
In most cases you **don't** want images imported when dealing with 2D
and GUI. Just copy them to the filesystem. Read the tutorial on
:ref:`doc_managing_image_files` before continuing! For 3D,
textures are always imported by the 3D scene importer, so importing
those is only useful when importing a texture used for 3D that doesn't
come with the 3D scene (for example, in a shader). The flags and options
are the same as here, so reading the rest of the document might help
too.
OK, you *might* want to import them
-----------------------------------
So, if you have read the previous tutorial on the texture exporter, the
texture importer gives you more fine-grained control on how textures
are imported. If you want to change flags such as repeat, filter,
mipmaps, fix edges, etc. ***PER texture***, importing them is the best
way to accomplish this (since you can't save such flags in a standard
image file).
Lack of MipMaps
---------------
Images in 3D hardware are scaled with a (bi)linear filter, but this
method has limitations. When images are shrunk too much, two problems
arise:
- **Aliasing**: Pixels are skipped too much, and the image shows
discontinuities. This decreases quality.
- **Cache Misses**: Pixels being read are too far apart, so texture
cache reads a lot more data than it should. This decreases
performance.
.. image:: /img/imagemipmap.png
To solve this, mipmaps are created. Mipmaps are versions of the image
shrunk by half in both axis, recursively, until the image is 1 pixel of
size. When the 3D hardware needs to shrink the image, it finds the
largest mipmap it can scale from, and scales from there. This improves
performance and image quality.
.. image:: /img/mipmaps.png
Godot automatically creates mipmaps upon load for standard image files.
This process is time consuming (although not much) and makes load times
a little worse. Pre-importing the textures allows the automatic
generation of mipmaps.
Unwanted MipMaps
----------------
Remember the previous point about mipmaps? Yes, they are cool, but
mobile GPUs only support them if the textures are in power of 2
dimensions (i.e. 256x256 or 512x128). In these platforms, Godot will
stretch and enlarge the texture to the closest power of 2 size and then
generate the mipmaps. This process takes more of a performance hit and
it might degrade the quality a little more.
Because of this, there are some scenarios when it may be desirable to
not use them, and just use a linear filter. One of them is when working
with graphical user interfaces (GUIs). Usually they are made of large
images and don't stretch much. Even if the screen resolution is in a
larger or smaller value than original art, the amount of stretch is not
as much and the art can retain the quality. Pre-importing the textures
also allows the disabling of mipmap generation.
Blending artifacts
------------------
The `blending
equation <http://en.wikipedia.org/wiki/Alpha_compositing>`__ used by
applications like Photoshop is too complex for realtime. There are
better approximations such as `pre-multiplied
alpha <http://blogs.msdn.com/b/shawnhar/archive/2009/11/06/premultiplied-alpha.aspx?Redirected=true>`__,
but they impose more stress in the asset pipeline. In the end, we are
left with textures that have artifacts in the edges, because apps such
as Photoshop store white pixels in completely transparent areas. Such
white pixels end up showing thanks to the texture filter.
Godot has an option to fix the edges of the image (by painting invisible
pixels the same color as the visible neighbours):
.. image:: /img/fixedborder.png
However, this must be done every time the image changes. Pre-Importing
the textures makes sure that every time the original file changes, this
artifact is fixed upon automatic re-import.
Texture flags
-------------
Textures have flags. The user can choose for them to repeat or clamp to
edges (when UVs exceed the 0,0,1,1 boundary). The magnifying filter can
also be turned off (for a Minecraft-like effect). Such values can not be
edited in standard file formats (png, jpg, etc.), but can be edited and
saved in Godot .tex files. Then again, the user may not want to change
the values every time the texture changes. Pre-Importing the textures
also takes care of that.
Texture compression
-------------------
Aside from the typical texture compression, which saves space on disk
(.png, jpg, etc.), there are also texture compression formats that save
space in memory (more specifically video memory. This allows to have
much better looking textures in games without running out of memory, and
decrease memory bandwidth when reading them so they are a big plus.
There are several video texture compression formats, none of which are
standard. Apple uses PVRTC. PC GPUs, consoles and nVidia Android devices use
S3TC (BC), other chipsets use other formats. OpenGL ES 3.0 standardized on ETC
format, but we are still a few years away from that working everywhere.
Still, when using this option, Godot converts and compresses to the
relevant format depending on the target platform (as long as the user
pre-imported the texture and specified video ram compression!).
This kind of compression is often not desirable for many types of 2D games
and UIs because it is lossy, creating visual artifacts. This is especially
noticeable on games that use the trendy vectory social game artwork.
However, the fact that it saves space and improves performance may make up for
it.
The 3D scene importer always imports textures with this option turned
on.
Atlases
-------
Remember how mobile GPUs have this limitation of textures having to be
in power of 2 sizes to be able to generate mimpmaps for optimum
stretching? What if we have a lot of images in different random sizes?
All will have to be scaled and mipmapped when loaded (using more CPU and
memory) or when imported (taking more storage space). This is probably still
OK, but there is a tool that can help improve this situation.
Atlases are big textures that fit a lot of small textures inside
efficiently. Godot supports creating atlases in the importer, and the
imported files are just small resources that reference a region of the
bigger texture.
Atlases can be a nice solution to save some space on GUI or 2D artwork
by packing everything together. The current importer is not as useful
for 3D though (3D Atlases are created differently, and not all 3D
models can use them).
As a small plus, atlases can decrease the amount of "state changes" when
drawing. If a lot of objects that are drawn using several different
textures are converted to an atlas, then the texture rebinds per object
will go from dozens or hundreds to one. This will give the performance a
small boost.
Artists use PSD
---------------
Still wondering whether to use the texture importer or not? Remember
that in the end, artists will often use Photoshop anyway, so it may be
wiser to just let the import subsystem to take care of importing and
converting the PSD files instead of asking the artist to save a png and
copy it to the project every time.
Texture importer
----------------
Finally! It's time to take a look at the texture importer. There are 3
options in the import menu. They are pretty much (almost) the same
dialog with a different set of defaults.
.. image:: /img/importtex.png
When selected, the texture import dialog will appear. This is the
default one for 2D textures:
.. image:: /img/import_images.png
Each import option has a function, explained as follows:
Source texture(s)
~~~~~~~~~~~~~~~~~
One or more source images can be selected from the same folder (this
importer can do batch-conversion). This can be from inside or outside
the project.
Target path
~~~~~~~~~~~
A destination folder must be provided. It must be inside the project, as
textures will be converted and saved to it. Extensions will be changed
to .tex (Godot resource file for textures), but names will be kept.
Texture format
~~~~~~~~~~~~~~
This combo allows to change the texture format (compression in this
case):
.. image:: /img/compressopts.png
Each of the four options described in this table together with their
advantages and disadvantages ( |good| = Best, |bad| =Worst ):
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| | Uncompressed | Compress Lossless (PNG) | Compress Lossy (WebP) | Compress VRAM |
+================+========================+===========================+=========================+======================================================+
| Description | Stored as raw pixels | Stored as PNG | Stored as WebP | Stored as S3TC/BC,PVRTC/ETC, depending on platform |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| Size on Disk | |bad| Large | |regular| Small | |good| Very Small | |regular| Small |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| Memory Usage | |bad| Large | |bad| Large | |bad| Large | |good| Small |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| Performance | |regular| Normal | |regular| Normal | |regular| Normal | |good| Fast |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| Quality Loss | |good| None | |good| None | |regular| Slight | |bad| Moderate |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
| Load Time | |regular| Normal | |bad| Slow | |bad| Slow | |good| Fast |
+----------------+------------------------+---------------------------+-------------------------+------------------------------------------------------+
Texture options
~~~~~~~~~~~~~~~
Provided are a small amount of options for fine grained import control:
- **Streaming Format** - This does nothing as of yet, but a texture
format for streaming different mipmap levels is planned. Big engines
have support for this.
- **Fix Border Alpha** - This will fix texture borders to avoid the
white auras created by white invisible pixels (see the rant above).
- **Alpha Bit Hint** - Godot auto-detects if the texture needs alpha
bit support for transparency (instead of full range), which is useful
for compressed formats such as BC. This forces alpha to be 0 or 1.
- **Compress Extra** - Some VRAM compressions have alternate formats
that compress more at the expense of quality (PVRTC2 for example). If
this is ticked, texture will be smaller but look worse.
- **No MipMaps** - Force imported texture to NOT use mipmaps. This may
be desirable in some cases for 2D (as explained in the rant above),
though it's NEVER desirable for 3D.
- **Repeat** - Texture will repeat when UV coordinates go beyond 1 and
below 0. This is often desirable in 3D, but may generate artifacts in
2D.
- **Filter** - Enables linear filtering when a texture texel is larger
than a screen pixel. This is usually turned on, unless it's required
for artistic purposes (Minecraft look, for example).
.. |bad| image:: /img/bad.png
.. |good| image:: /img/good.png
.. |regular| image:: /img/regular.png
learning/workflow/assets/importing_translations.rst
+9 -14
View File
@@ -67,20 +67,15 @@ uppercase, to differentiate from other strings). Here's an example:
| BYE | Good Bye | Adiós | さようなら |
+---------+------------------+----------------+--------------+
Import dialog
-------------
CSV Importer
------------
The import dialog takes a CSV file in the previously described format
and generates several compressed translation resource files inside the
project.
Godot will treat CSV files as translations by default. It will import them
and generate one or more compressed translation resource files next to it.
Selecting a CSV file autodetects the languages from the first row and
determines which column represents which language. It is possible to
change this manually, by selecting the language for each column.
.. image:: /img/trans.png
The import dialog also can add the translation to the list of
translations to load when the game runs, specified in engine.cfg (or the
project properties). Godot allows loading and removing translations at
Importing will also add the translation to the list of
translations to load when the game runs, specified in project.godot (or the
project settings). Godot allows loading and removing translations at
runtime as well.
learning/workflow/assets/index.rst
+2 -4
View File
@@ -6,9 +6,7 @@ Assets workflow
:name: toc-learn-workflow-assets
import_process
managing_image_files
importing_textures
importing_images
importing_audio_samples
importing_fonts
importing_translations
exporting_images
learning/workflow/assets/managing_image_files.rst
-152
View File
@@ -1,152 +0,0 @@
.. _doc_managing_image_files:
Managing image files
====================
If you have read the previous tutorials on :ref:`doc_resources` and
:ref:`doc_filesystem`, at this point you know that regular image files
(.png, .jpg, etc.) are treated as regular resources in Godot.
Unlike texture resources (.tex files), image files contain no extra
information on tiling (texture repeat), mipmaps or filtering. Editing
this information and saving the texture back will not have any effect,
since such formats can't contain that information.
Image loader
------------
Loading of images is done by the image loader. The behavior of the
loader for all image files can be changed in the Project Settings dialog
(Scene -> Project Settings). There is a section with values that
are used for all image resources:
.. image:: /img/imgloader.png
Image loader options
--------------------
Filter
~~~~~~
Filter is used when the image is stretched more than its original size,
so a texel in the image is bigger than a pixel on the screen. Turning
off the filter produces a retro-like look:
.. image:: /img/imagefilter.png
Repeat
~~~~~~
Repeat is mainly used for 3D textures, so it's off by default (textures
are imported with the scenes and usually are not in the project as image
files). When using UV coordinates (something not as common in 2D), and
the UV value goes beyond the 0,0,1,1 rect, the texture repeats instead
of clamping to the edge.
Mipmaps
~~~~~~~
When the mipmaps option is enabled, Godot will generate mipmaps.
Mipmaps are versions of the image shrunk by half in both axes,
recursively, until the image is 1 pixel of size. When the 3D hardware
needs to shrink the image, it finds the largest mipmap it can scale
from, and scales from there. This improves performance and image
quality.
.. image:: /img/mipmaps.png
When mipmaps are disabled, images start distorting badly when shrunk
excessively:
.. image:: /img/imagemipmap.png
Alpha blending
~~~~~~~~~~~~~~
The `blending
equation <http://en.wikipedia.org/wiki/Alpha_compositing>`__ used by
applications like Photoshop is too complex for real-time. There are
better approximations such as `pre-multiplied
alpha <http://blogs.msdn.com/b/shawnhar/archive/2009/11/06/premultiplied-alpha.aspx?Redirected=true>`__,
but they impose more stress in the asset pipeline. In the end, we are
left with textures that have artifacts in the edges, because apps such
as Photoshop store white pixels in completely transparent areas. Such
white pixels end up showing thanks to the texture filter (when active).
Godot has an option to fix the edges of the image (by painting invisible
pixels the same color as the visible neighbours):
.. image:: /img/fixedborder.png
To do this, open the image from the resources tab, or edit it from the
property editor from another node or resource, then go to the object
options and select "Fix Alpha Edges", then save it.
.. image:: /img/imagefixalpha.png
Since fixing this in so many images can be a little annoying, both
Texture Import and Image Export can also perform this operation.
Texture import
~~~~~~~~~~~~~~
Sometimes, it might be desirable to change the above settings per image.
Unfortunately, the image loader settings are global. Texture flags also
can't be saved in a regular .png or .jpg file.
For such cases, the image can be imported as a texture (.tex), where the
individual flags can be changed. Godot also keeps track of the original
file and will re-import if it changes.
Importing also allows conversion to other formats (WebP, or RAM
compression) which might be of use in some cases. More information on
the :ref:`doc_importing_textures` page.
Image export
~~~~~~~~~~~~
It is also possible to convert images to other formats (WebP or RAM
compression) on export, as well as instructing the exporter to create an
Atlas for a set of images. It is also possible to ask the exporter to
scale all images (or selected groups).
More information on the :ref:`doc_exporting_images` page.
Fixing PNGs iCCP chunk
----------------------
With the upgrade of libpng to 1.6.23, libpng became more strict in terms of
enforcing iCC profile correctness. This means that it now warns when it comes
across an image with a non-conforming iCC chunk.
WARNING: _png_warn_function: iCCP: known incorrect sRGB profile
This can be fixed by either using a tool that exports PNGs with the correct
iCC profile (in some tools this profile can even be manually changed on export)
or using a tool that removes/fixes the iCC chunks.
Linux/Mac
~~~~~~~~~
Using ImageMagicks ``convert`` or ``mogrify`` fixes these warnings.
To fix all PNGs in a project folder do:
.. code-block:: shell
$ find . -type f -name "*.png" -exec convert {} {} \;
``pngcheck`` is also useful in locating the non-conforming images:
.. code-block:: shell
find . -type f -name "*.png" -exec pngcheck {} \;
Windows
~~~~~~~
Using `optiPNG <http://optipng.sourceforge.net/>` fixes these warnings on Windows.
To fix a PNG inplace do:
.. code-block:: shell
optipng -clobber -strip all file.png