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

learning/workflow/assets/exporting_images.rst

@@ -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

@@ -3,162 +3,90 @@
 Import process
 ==============
 
-What is it for?
----------------
-
-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.
-
-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.
-
-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.
-
-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.
-
-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).
-
-Does it always work?
---------------------
-
-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.
-
-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:
-
--  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.
-
-Both the import system and the custom tools provided will improve over
-time as more use cases are revealed to us.
-
-Importing assets
-----------------
-
-Source asset location
-~~~~~~~~~~~~~~~~~~~~~
-
-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.
-
-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.
-
-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.
-
-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:
-
-::
-
-    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
-
-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.
-
-Import dialogs
-~~~~~~~~~~~~~~
-
-Godot provides for importing several types of assets, all of them can be
-accessed from the import dialog:
-
-.. image:: /img/import.png
-
-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/importdialogs.png
-
-More information about each specific type of asset can be found in
-specific sections, such as `Importing Textures <import_textures>`__.
-
-Tracking changes and re-importing
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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
-~~~~~~~~~~~~~~~~~~~~~
+Importing assets in Godot 3.0+
+------------------------------
 
-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.
+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.
+
+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.
+
+This allows changing all the import parameters transparently.
+
+Changing import parameters
+--------------------------
+
+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:
+
+.. image:: /img/asset_workflow1.png
+
+And, after adjusting the parameters, just press "Reimport". The parameters
+used will be only for this asset and will be used on future reimports.
+
+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.
+
+Automatic reimport
+------------------
+
+When the source asset changes, Godot will perform and automatic reimport
+of it, applying the preset configured for that specific asset.
+
+Files generated
+-----------------
+
+Importing will add an extra <asset>.import file, containing the import
+configuration. Make sure to commit these to your version control system!
+
+.. image:: /img/asset_workflow4.png
+
+Additionally, extra assets will be presset in the hidden res://.import folder:
+
+.. image:: /img/asset_workflow5.png
+
+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
+-----------------------------
+
+Some source assets can be imported as different types of resources. 
+For this, just select the relevant type of resource desired and
+press "Reimport":
+
+.. image:: /img/asset_workflow2.png
+
+
+Changing default import parameters
+-----------------------------------
+
+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:
+
+.. image:: /img/asset_workflow3.png
+
+Simplicity is key!
+------------------
+
+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. 
+
+There are many types of assets available for import, so please continue reading to understand how to work
+with all of them!
 
-.. 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

@@ -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?"
-
-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.
-
-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.
-
-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.
-
-These often result in extremely large files to integration into a game engine
-with sound effects taking dozens of megabytes.
-
-How much does quality matter?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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
+Raw audio data in general is large and undesired. Godot provides two main
+options to import your audio data: WAV and OGG Vorbis.
+
+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.
+
+
+.. image:: /img/audio_stram_import.png
+
+Here is a comparative chart.
+
++-------------------------------+---------------------+
+| 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                |
++-------------------------------+---------------------+
+
+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.
+
+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.
-
-.. image:: /img/trim.png
-
-Importing audio samples
------------------------
+add latency to the moment they are played back. 
 
-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

@@ -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

@@ -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

@@ -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

@@ -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.
+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.
 
-.. 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
-runtime as well.

learning/workflow/assets/index.rst

@@ -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

@@ -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