Merge pull request #6782 from Calinou/update-import-docs

Update resource importing documentation for Godot 4.0

tutorials/3d/3d_rendering_limitations.rst

@@ -23,6 +23,11 @@ your texture to display correctly on all platforms, you should avoid using
 textures larger than 4096×4096 and use a power of two size if the texture needs
 to repeat.
 
+To limit the size of a specific texture that may be too large to render, you can
+set the **Process > Size Limit** import option to a value greater than ``0``.
+This will reduce the texture's dimensions on import (preserving aspect ratio)
+without affecting the source file.
+
 .. _doc_3d_rendering_limitations_color_banding:
 
 Color banding

tutorials/3d/standard_material_3d.rst

@@ -448,6 +448,8 @@ World Triplanar
 When using triplanar mapping, it is computed in object local space. This
 option makes it use world space instead.
 
+.. _doc_standard_material_3d_sampling:
+
 Sampling
 --------
 

tutorials/3d/volumetric_fog.rst

@@ -214,6 +214,8 @@ the following properties in FogMaterial:
   of the FogVolume. This can be used to vary fog density within the FogVolume
   with any kind of static pattern. For animated effects, consider using a custom
   :ref:`fog shader <doc_fog_shader>`.
+  You can import any image as a 3D texture by
+  :ref:`changing its import type in the Import dock <doc_importing_images_changing_import_type>`.
 
 Custom FogVolume shaders
 ------------------------

tutorials/assets_pipeline/import_process.rst

@@ -3,40 +3,48 @@
 Import process
 ==============
 
-Importing assets in Godot 3.0+
-------------------------------
+Importing assets in Godot
+-------------------------
 
-Previously, importing assets in Godot 2.x required manual maintenance
-of a separate directory with source assets. Without doing this, it was
-impossible to specify how to convert and change import flags for
-textures, audio files, scenes, etc.
+To import assets in Godot, place your assets (image files, scenes, audio
+files, fonts, etc) directly in the project folder. There are 2 ways to achieve this:
 
-In Godot 3.0+, we use a more modern approach to importing: Simply drop
-your assets (image files, scenes, audio files, fonts, etc) directly in the
-project folder (copy them manually with your OS file explorer).
-Godot will automatically import these files internally
-and keep the imported resources hidden in a ``res://.import`` folder.
+- **For any file type:** Copy files manually with your operating system's file manager.
+- **For file types that can be imported by Godot:**
+  Drag-and-drop files from the operating system's file manager to the editor's FileSystem dock.
+  This only works with *resource* file types (i.e. file types that Godot can import).
 
-This means that when trying to access imported assets through code you
+Godot will automatically import these files internally and keep the imported
+resources hidden in a ``res://.godot/imported/`` folder.
+
+This means that when trying to access imported assets through code, you
 need to use the :ref:`Resource Loader<class_ResourceLoader>` as it will
 automatically take into account where the internal files are saved. If you
-try and access an imported asset using the :ref:`FileAccess <class_FileAccess>` class
-it will work in the editor, but break in the exported project.
+try and access an imported asset using the :ref:`FileAccess <class_FileAccess>` class,
+it will work in the editor, but **it will break in the exported project**.
 
 However, the :ref:`Resource Loader<class_ResourceLoader>` cannot access
-non imported files, only the :ref:`FileAccess <class_FileAccess>` class can.
+non-imported files. Only the :ref:`FileAccess <class_FileAccess>` class can.
 
 Changing import parameters
 --------------------------
 
-To change the import parameters of an asset in Godot (again, keep in mind
-import parameters are only present in non-native Godot resource types)
-select the relevant resource in the filesystem dock:
+.. note::
 
-.. image:: img/asset_workflow1.png
+    Import parameters are only present in *non-native* Godot resource types.
+    This means Godot's own scene and resource file formats (``.tscn``, ``.scn``,
+    ``.tres``, ``.res``) don't have import options you can select in the Import
+    dock.
 
-Then, after adjusting the parameters, press "Reimport". These parameters
-will only be used for this asset and on future reimports.
+To change the import parameters of an asset in Godot, select the relevant
+resource in the FileSystem dock:
+
+.. image:: img/import_process_example.webp
+
+After adjusting the parameters, click **Reimport**. Be careful: if you select
+another file in the FileSystem dock before clicking **Reimport**, changes will
+be discarded. After clicking **Reimport**, the chosen parameters will only be
+used for this asset and on future reimports.
 
 Changing the import parameters of several assets at the same time is also
 possible. Simply select all of them together in the resources dock and the
@@ -66,48 +74,77 @@ 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!
+Importing will add an extra ``<asset>.import`` file next to the source file,
+containing the import configuration.
 
-.. image:: img/asset_workflow4.png
+**Make sure to commit these files to your version control system**, as these
+files contain important metadata.
 
-Additionally, extra assets will be preset in the hidden ``res://.import`` folder:
+::
 
-.. image:: img/asset_workflow5.png
+    $ ls
+    example.png
+    example.png.import
+    project.godot
+
+Additionally, extra assets will be present in the hidden
+``res://.godot/imported/`` folder:
+
+::
+
+    $ ls .godot/imported
+    example.png-218a8f2b3041327d8a5756f3a245f83b.ctex
+    example.png-218a8f2b3041327d8a5756f3a245f83b.md5
 
 If any of the files present in this folder is erased (or the whole folder), the
-asset or assets will be reimported automatically. As such, committing this folder
-to the version control system is optional. It can shorten
-reimporting time when checking out on another computer, but it takes considerably
-more space and transfer time. Pick your poison!
+asset or assets will be reimported automatically. As such, committing the
+``.godot/`` folder to the version control system is not recommended. While
+committing this folder can shorten reimporting time when checking out on another
+computer, it requires considerably more space and bandwidth.
+
+The default version control metadata that can be generated on project creation
+will automatically ignore the ``.godot/`` folder.
 
 Changing import resource type
 -----------------------------
 
-Some source assets can be imported as different types of resources.
-For this, select the relevant type of resource desired and
-press "Reimport":
+Some source assets can be imported as different types of resources. For this,
+select the relevant type of resource desired then click **Reimport**:
 
-.. image:: img/asset_workflow2.png
+.. image:: img/import_process_changing_import_type.webp
 
+.. note::
+
+    For technical reasons, the editor must be restarted after changing an import
+    type in the Import dock.
 
 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:
+Different types of projects might require different defaults. Changing the import
+options to a predefined set of options can be achieved by using the
+**Preset...** Menu. Besides some resource types offering presets, the default
+settings can be saved and cleared too:
 
-.. image:: img/asset_workflow3.png
+.. image:: img/import_process_change_preset.webp
 
-Simplicity is key!
-------------------
+The default import parameters for a given resource type can be changed
+project-wide using the **Import Defaults** tab of the Project Settings dialog:
 
-This workflow is aimed to be simple and take very little time to get used to. It also enforces a more
-correct way to deal with resources.
+.. image:: img/import_process_import_defaults.webp
 
-There are many types of assets available for import, so please continue reading to understand how to work
-with all of them!
+Further reading
+---------------
+
+This workflow takes a little time to get used to, but it enforces a more correct
+way to deal with resources.
+
+There are many types of assets available for import. Continue reading to
+understand how to work with all of them:
+
+- :ref:`doc_importing_images`
+- :ref:`doc_importing_audio_samples`
+- :ref:`doc_importing_3d_scenes`
+- :ref:`doc_importing_translations`

tutorials/assets_pipeline/importing_audio_samples.rst

@@ -3,29 +3,31 @@
 Importing audio samples
 =======================
 
-Supported files
----------------
+Supported audio formats
+-----------------------
 
-Godot provides three options to import your audio data: WAV, Ogg Vorbis
-and MP3.
+Godot provides 3 options to import your audio data: WAV, Ogg Vorbis and MP3.
 
-Each has different advantages.
+Each format has different advantages:
 
-* WAV files use raw data or light compression (IMA-ADPCM). They are lightweight
+- WAV files use raw data or light compression (IMA-ADPCM). They are lightweight
   on the CPU to play back (hundreds of simultaneous voices in this format are
   fine). The downside is that they take up a lot of disk space.
-* Ogg Vorbis files use a stronger compression that results in much
+- Ogg Vorbis files use a stronger compression that results in much
   smaller file size, but require significantly more processing power to
   play back.
-* MP3 files use better compression than WAV with IMA-ADPCM, but worse than
+- MP3 files use better compression than WAV with IMA-ADPCM, but worse than
   Ogg Vorbis. This means that a MP3 file with roughly equal quality to
   Ogg Vorbis will be significantly larger. On the bright side, MP3 requires
-  less CPU usage to play back compared to Ogg Vorbis. This makes MP3 useful
-  for mobile and HTML5 projects where CPU resources are limited, especially
-  when playing multiple compressed sounds at the same time (such as long
-  ambient sounds).
+  less CPU usage to play back compared to Ogg Vorbis.
 
-Here is a comparative chart.
+.. note::
+
+    If you've compiled the Godot editor from source with specific modules disabled,
+    some formats may not be available.
+
+Here is a comparative chart representing the file size of 1 second of audio with
+each format:
 
 +-----------------------------+-------------------+
 | Format                      | 1 second of audio |
@@ -43,39 +45,262 @@ Here is a comparative chart.
 | Ogg Vorbis 96 Kb/s, stereo  | 12 KB             |
 +-----------------------------+-------------------+
 
-Consider using WAV for short and repetitive sound effects, and Ogg Vorbis
-for music, speech, and long sound effects.
+Note that the MP3 and Ogg Vorbis figures can vary depending on the encoding
+type. The above figures use :abbr:`CBR (Constant Bit Rate)` encoding for
+simplicity, but most Ogg Vorbis and MP3 files you can find online are encoded
+with :abbr:`VBR (Variable Bit Rate)` encoding which is more efficient.
+VBR encoding makes the effective audio file size depend on how "complex" the
+source audio is.
+
+.. tip::
+
+    Consider using WAV for short and repetitive sound effects, and Ogg Vorbis for
+    music, speech, and long sound effects. MP3 is useful for mobile and web projects
+    where CPU resources are limited, especially when playing multiple compressed
+    sounds at the same time (such as long ambient sounds).
+
+Importing audio samples
+-----------------------
+
+Several options are available in the Import dock after selecting a WAV file in
+the FileSystem dock:
+
+.. figure:: img/importing_audio_samples_import_options_wav.webp
+   :align: center
+   :alt: Import options in the Import dock after selecting a WAV file in the FileSystem dock
+
+   Import options in the Import dock after selecting a WAV file in the FileSystem dock
+
+The set of options available after selecting a Ogg Vorbis or MP3 file is different:
+
+.. figure:: img/importing_audio_samples_import_options_mp3.webp
+   :align: center
+   :alt: Import options in the Import dock after selecting a MP3 file in the FileSystem dock
+
+   Import options in the Import dock after selecting a MP3 file in the
+   FileSystem dock. Options are identical for Ogg Vorbis files.
+
+After importing a sound, you can play it back using the AudioStreamPlayer,
+AudioStreamPlayer2D or AudioStreamPlayer3D nodes. See :ref:`doc_audio_streams`
+for more information.
+
+Import options (WAV)
+--------------------
+
+Force > 8 Bit
+-------------
+
+If enabled, forces the imported audio to use 8-bit quantization if the source
+file is 16-bit or higher.
+
+Enabling this is generally not recommended, as 8-bit quantization decreases
+audio quality significantly. If you need smaller file sizes, consider using Ogg
+Vorbis or MP3 audio instead.
+
+Force > Mono
+------------
+
+If enabled, forces the imported audio to be mono if the source file is stereo.
+This decreases the file size by 50% by merging the two channels into one.
+
+Force > Max Rate
+----------------
+
+If set to a value greater than ``0``, forces the audio's sample rate to be
+reduced to a value lower than or equal to the value specified here.
+
+This can decrease file size noticeably on certain sounds, without impacting
+quality depending on the actual sound's contents. See
+:ref:`doc_importing_audio_samples_best_practices` for more information.
+
+Edit > Trim
+-----------
+
+The source audio file may contain long silences at the beginning and/or the end.
+These silences are inserted by :abbr:`DAWs (Digital Audio Workstations)` when
+saving to a waveform, which increases their size unnecessarily and add latency
+to the moment they are played back.
+
+Enabling **Trim** will automatically trim the beginning and end of the audio if
+it's lower than -50 dB *after* normalization (see **Edit > Normalize** below). A
+fade-in/fade-out period of 500 samples is also used during trimming to avoid
+audible pops.
+
+Edit > Normalize
+----------------
+
+If enabled, audio volume will be *normalized* so that its peak volume is equal
+to 0 dB. When enabled, normalization will make audio sound louder depending on
+its original peak volume.
+
+Edit > Loop Mode
+----------------
+
+Unlike Ogg Vorbis and MP3, WAV files can contain metadata to indicate whether
+they're looping (in addition to loop points). By default, Godot will follow this
+metadata, but you can choose to apply a specific loop mode:
+
+- **Disabled:** Don't loop audio, even if metadata indicates the file should be
+  played back looping.
+- **Forward:** Standard audio looping.
+- **Ping-Pong:** Play audio forward until it's done playing, then play it
+  backward and repeat. This is similar to mirrored texture repeat, but for
+  audio.
+- **Backward:** Play audio in reverse and loop back to the end when done playing.
+
+When choosing one of the **Forward**, **Ping-Pong** or **Backward** loop modes,
+loop points can also be defined to make only a specific part of the sound loop.
+**Loop Begin** is set in seconds after the beginning of the audio file. **Loop
+End** is also set in seconds after the beginning of the audio file, but will use
+the end of the audio file if set to ``-1``.
+
+.. warning::
+
+    In AudioStreamPlayer, the ``finished`` signal won't be emitted for looping
+    audio when it reaches the end of the audio file, as the audio will keep
+    playing indefinitely.
+
+Compress > Mode
+---------------
+
+Two compression modes can be chosen for WAV files: **Disabled** (default) or
+**RAM (Ima-ADPCM)**. **RAM (Ima-ADPCM)** reduces file size and memory usage a
+little, at the cost of decreasing quality in an audible manner.
+
+Ogg Vorbis and MP3 don't decrease quality as much and can provide greater file
+size reductions, at the cost of higher CPU usage during playback. This higher
+CPU usage is usually not a problem (especially with MP3), unless playing dozens
+of compressed sounds at the same time on mobile/web platforms.
+
+Import options (Ogg Vorbis and MP3)
+-----------------------------------
+
+Loop
+^^^^
+
+If enabled, the audio will begin playing at the beginning after playback ends by
+reaching the end of the audio.
+
+.. warning::
+
+    In AudioStreamPlayer, the ``finished`` signal won't be emitted for looping
+    audio when it reaches the end of the audio file, as the audio will keep
+    playing indefinitely.
+
+Loop Offset
+^^^^^^^^^^^
+
+The loop offset determines where audio will start to loop after playback reaches
+the end of the audio. This can be used to only loop a part of the audio file,
+which is useful for some ambient sounds or music. The value is determined in
+seconds relative to the beginning of the audio, so ``0`` will loop the entire
+audio file.
+
+Only has an effect if **Loop** is enabled.
+
+A more convenient editor for **Loop Offset** is provided in the
+:ref:`Advanced import settings <doc_importing_audio_samples_advanced_import_settings>`
+dialog, as it lets you preview your changes without having to reimport the audio.
+
+BPM
+^^^
+
+The Beats Per Minute of the audio track. This should match the BPM measure that
+was used to compose the track. This is only relevant for music that wishes to
+make use of interactive music functionality (not implemented yet), not sound
+effects.
+
+A more convenient editor for **BPM** is provided in the
+:ref:`Advanced import settings <doc_importing_audio_samples_advanced_import_settings>`
+dialog, as it lets you preview your changes without having to reimport the audio.
+
+Beat Count
+^^^^^^^^^^
+
+The beat count of the audio track. This is only relevant for music that wishes
+to make use of interactive music functionality (not implemented yet), not sound
+effects.
+
+A more convenient editor for **Beat Count** is provided in the
+:ref:`Advanced import settings <doc_importing_audio_samples_advanced_import_settings>`
+dialog, as it lets you preview your changes without having to reimport the audio.
+
+Bar Beats
+^^^^^^^^^
+
+The number of bars within a single beat in the audio track. This is only
+relevant for music that wishes to make use of interactive music functionality
+(not implemented yet), not sound effects.
+
+A more convenient editor for **Bar Beats** is provided in the
+:ref:`Advanced import settings <doc_importing_audio_samples_advanced_import_settings>`
+dialog, as it lets you preview your changes without having to reimport the audio.
+
+.. _doc_importing_audio_samples_advanced_import_settings:
+
+Advanced import settings (Ogg Vorbis and MP3)
+---------------------------------------------
+
+If you double-click an Ogg Vorbis or MP3 file in the FileSystem dock (or choose
+**Advanced…** in the Import dock), you will see a dialog appear:
+
+.. figure:: img/importing_audio_samples_advanced_import_settings.webp
+   :align: center
+   :alt: Advanced dialog when double-clicking a Ogg Vorbis or MP3 file in the FileSystem dock
+
+   Advanced dialog when double-clicking a Ogg Vorbis or MP3 file in the FileSystem dock
+
+This dialog allows you to edit the audio's loop point with a real-time preview,
+in addition to the :abbr:`BPM (Beats Per Minute)`, beat count and bar beats.
+These 3 settings are currently unused, but they will be used in the future for
+interactive music support (which allows smoothly transitioning between different
+music tracks).
+
+.. note::
+
+    Unlike WAV files, Ogg Vorbis and MP3 only support a "loop begin" loop point,
+    not a "loop end" point. Looping can also be only be standard forward
+    looping, not ping-pong or backward.
+
+.. _doc_importing_audio_samples_best_practices:
 
 Best practices
 --------------
 
+Use appropriate quality settings
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+While keeping pristine-quality audio sources is important if you're performing
+editing, using the same quality in the exported project is not necessary. For
+WAV files, Godot offers several import options to reduce the final file size
+without modifying the source file on disk.
+
+To reduce memory usage and file size, choose an appropriate quantization,
+sample rate and number of channels for your audio:
+
+- There's no *audible* benefit to using 24-bit audio, especially in a game
+  where several sounds are often playing at the same time (which makes it
+  harder to appreciate individual sounds).
+- Unless you are slowing down the audio at run-time, there's no *audible*
+  benefit to using a sample rate greater than 48 kHz. If you wish to keep a
+  source with a higher sample rate for editing, use the **Force > Max Rate**
+  import option to limit the sample rate of the imported sound (only available
+  for WAV files).
+- Many sound effects can generally be converted to mono as opposed to stereo.
+  If you wish to keep a source with stereo for editing, use the **Force > Mono**
+  import option to convert the imported sound to mono (only available for WAV files).
+- Voices can generally be converted to mono, but can also have their sample rate
+  reduced to 22 kHz without a noticeable loss in quality (unless the voice is
+  very high-pitched). This is because most human voices never go past 11 kHz.
+
+Use real-time audio effects to reduce file size
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Godot has an :ref:`extensive bus system <doc_audio_buses>` 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!
+reducing their size greatly and ensuring correct trimming.
 
 .. image:: img/reverb.png
 
-As you can see above, sound effects become huge with reverb added.
-
-Trimming
-~~~~~~~~
-
-One issue that happens often is that the waveform is 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.
-
-Importing as WAV with the **Trimming** option enabled solves
-this.
-
-Looping
-~~~~~~~
-
-Godot supports looping in the samples (tools such as Sound Forge or
-Audition can add loop points to WAV files). This is useful for sound
-effects, such as engines, machine guns etc. Ping-pong looping is also
-supported.
-
-As an alternative, the Import dock has a **Loop** option that enables
-looping for the entire sample when importing.
+As you can see above, sound effects become much larger in file size with reverb
+added.

tutorials/assets_pipeline/importing_images.rst

@@ -1,4 +1,4 @@
-.. _doc_import_images:
+.. _doc_importing_images:
 
 Importing images
 ================
@@ -23,10 +23,11 @@ Godot can import the following image formats:
   - Precision is limited to 8 bits per channel upon importing (no HDR images).
 - Truevision Targa (``.tga``)
 - SVG (``.svg``, ``.svgz``)
-  - SVGs are rasterized using `NanoSVG <https://github.com/memononen/nanosvg>`__
+  - SVGs are rasterized using `ThorVG <https://www.thorvg.org/>`__
   when importing them. Support is limited; complex vectors may not render correctly.
-  For complex vectors, rendering them to PNGs using Inkscape is often a better solution.
-  This can be automated thanks to its `command-line interface <https://wiki.inkscape.org/wiki/index.php/Using_the_Command_Line#Export_files>`__.
+  For complex vectors, rendering them to PNGs using `Inkscape <https://inkscape.org/>`__
+  is often a better solution. This can be automated thanks to its
+  `command-line interface <https://wiki.inkscape.org/wiki/index.php/Using_the_Command_Line#Export_files>`__.
 - WebP (``.webp``)
   - WebP files support transparency and can be compressed lossily or losslessly.
   The precision is limited to 8 bits per channel.
@@ -40,61 +41,159 @@ 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.
+in video memory. Their pixel data can't be accessed directly from the CPU
+without converting them back to an :ref:`class_Image` in a script. This is what
+makes drawing them efficient.
 
-Import options are vast:
+There are over a dozen import options that can be adjusted after selecting an
+image in the FileSystem dock:
 
-.. image:: img/image_import1.png
+.. figure:: img/importing_images_import_dock.webp
+   :align: center
+   :alt: Import options in the Import dock after selecting an image in the FileSystem dock
+
+   Import options in the Import dock after selecting an image in the FileSystem dock.
+   Some of these options are only visible with certain compression modes.
+
+.. _doc_importing_images_changing_import_type:
+
+Changing import type
+^^^^^^^^^^^^^^^^^^^^
+
+It is possible to choose other types of imported resources in the Import dock:
+
+- **BitMap:** 1-bit monochrome texture (intended to be used as a click mask in
+  :ref:`class_TextureButton` and :ref:`class_TouchScreenButton`). This resource
+  type cannot be displayed directly onto 2D or 3D nodes, but the pixel values
+  can be queried from a script using :ref:`get_bit
+  <class_BitMap_method_get_bit>`.
+- **Cubemap:** Import the texture as a 6-sided cubemap, with interpolation
+  between the cubemap's sides (seamless cubemaps), which can be sampled in
+  custom shaders.
+- **CubemapArray:** Import the texture as a collection of 6-sided cubemaps,
+  which can be sampled in custom shaders. This resource type can only be
+  displayed when using the Forward+ or Forward Mobile rendering methods, not
+  Compatibility.
+- **Font Data (Monospace Image Font):** Import the image as a bitmap font where
+  all characters have the same width. See :ref:`doc_gui_using_fonts`.
+- **Image:** Import the image as-is. This resource type cannot be displayed
+  directly onto 2D or 3D nodes, but the pixel values can be queried from a
+  script using :ref:`get_pixel<class_Image_method_get_pixel>`.
+- **Texture2D:** Import the image as a 2-dimensional texture, suited for display
+  on 2D and 3D surfaces. This is the default import mode.
+- **Texture2DArray:** Import the image as a collection of 2-dimensional textures.
+  Texture2DArray is similar to a 3-dimensional texture, but without
+  interpolation between layers. Built-in 2D and 3D shaders cannot display
+  texture arrays, so you must create a custom shader in :ref:`2D <doc_canvas_item_shader>`
+  or :ref:`3D <doc_spatial_shader>` to display a texture from a texture array.
+- **Texture3D:** Import the image as a 3-dimensional texture. This is *not* a 2D
+  texture applied onto a 3D surface. Texture3D is similar to a texture array, but
+  with interpolation between layers. Texture3D is typically used for
+  :ref:`class_FogMaterial` density maps in :ref:`volumetric fog
+  <doc_volumetric_fog>`, :ref:`class_Environment` 3D LUT color correction and
+  custom shaders.
+- **TextureAtlas:** Import the image as an *atlas* of different textures. Can be
+  used to reduce memory usage for animated 2D sprites. Only supported in 2D due
+  to missing support in built-in 3D shaders.
+
+.. note::
+
+    For technical reasons, the editor must be restarted after changing an import
+    type in the Import dock.
 
 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 automatically.
+The default import options (no mipmaps and **Lossless** compression) are suited
+for 2D, but are not ideal for most 3D projects. **Detect 3D** makes Godot aware
+of when a texture is used in a 3D scene (such as a texture in a
+:ref:`class_BaseMaterial3D`). If this happens, several import options are
+changed so the texture flags are friendlier to 3D. Mipmaps are enabled and the
+compression mode is changed to **VRAM Compressed** unless
+:ref:`doc_importing_images_detect_3d_compress_to` is changed. The texture is
+also reimported automatically.
 
-Compression
------------
+A message is printed to the Output panel when a texture is detected to be used in 3D.
 
-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.
+If you run into quality issues when a texture is detected to be used in 3D (e.g.
+for pixel art textures), change the
+:ref:`doc_importing_images_detect_3d_compress_to` option before using the
+texture in 3D, or change :ref:`doc_importing_images_compress_mode` to
+**Lossless** after using the texture in 3D. This is preferable to disabling
+**Detect 3D**, as mipmap generation remains enabled to prevent textures from
+looking grainy at a distance.
 
-Compress Mode
-~~~~~~~~~~~~~
+Import options
+--------------
 
-- **VRAM Compression:** This is the most common compression mode for 3D assets.
-  Size on disk is reduced and video memory usage is also decreased considerably
-  (usually by a factor between 4 and 6). This mode should be avoided for 2D as it
-  exhibits noticeable artifacts.
-- **Lossless Compression:** This is the most common compression mode for 2D assets.
+.. seealso::
+
+    In Godot 4.0, changing the texture filter and repeat mode is no longer done
+    in the import options.
+
+    Instead, texture filter and repeat modes are changed in the CanvasItem
+    properties in 2D (with a project setting acting as a default), and in a
+    :ref:`per-material configuration in 3D <doc_standard_material_3d_sampling>`.
+    In custom shaders, filter and repeat mode is changed on the ``sampler2D``
+    uniform using hints described in the :ref:`doc_shading_language`
+    documentation.
+
+.. _doc_importing_images_compress_mode:
+
+Compress > Mode
+^^^^^^^^^^^^^^^
+
+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.
+
+- **Lossless:** This is the default and most common compression mode for 2D assets.
   It shows assets without any kind of artifacting, and disk compression is
   decent. It will use considerably more amount of video memory than
   VRAM Compression, though. This is also the recommended setting for pixel art.
-- **Lossy Compression:** This is a good choice for large 2D assets. It has some
-  artifacts, but less than VRAM and the file size is several times lower
-  compared to Lossless or Uncompressed. Video memory usage isn't decreased by
-  this mode; it's the same as with Lossless Compression or Uncompressed.
-- **Uncompressed:** Only useful for formats that can't be compressed (such as
-  raw float images).
+- **Lossy:** This is a good choice for large 2D assets. It has some artifacts,
+  but less than VRAM compression and the file size is several times lower
+  compared to Lossless or VRAM Uncompressed. Video memory usage isn't decreased
+  by this mode; it's the same as with Lossless or VRAM Uncompressed.
+- **VRAM Compressed:** This is the default and most common compression mode for
+  3D assets. Size on disk is reduced and video memory usage is also decreased
+  considerably (usually by a factor between 4 and 6). This mode should be
+  avoided for 2D as it exhibits noticeable artifacts, especially for
+  lower-resolution textures.
+- **VRAM Uncompressed:** Only useful for formats that can't be compressed, such
+  as raw floating-point images.
+- **Basis Universal:** This alternative VRAM compression mode encodes the
+  texture to a format that can be transcoded to most GPU-compressed formats at
+  load-time. This provides very small files that make use of VRAM compression,
+  at the cost of lower quality compared to VRAM Compressed and slow compression
+  times. VRAM usage is usually the same as VRAM Compressed. Basis Universal does
+  not support floating-point image formats (the engine will internally fall back
+  to VRAM Compressed instead).
 
-In this table, each of the four options are described together with their
+.. note::
+
+    Even in 3D, "pixel art" textures should have VRAM compression disabled as it
+    will negatively affect their appearance, without improving performance
+    significantly due to their low resolution.
+
+In this table, each of the 5 options are described together with their
 advantages and disadvantages (|good| = best, |bad| = worst):
 
-+----------------+------------------------+-------------------------------+----------------------+------------------------------------------------------+
-|                | Uncompressed           | Compress Lossless             | Compress Lossy       | Compress VRAM                                        |
-+================+========================+===============================+======================+======================================================+
-| Description    | Stored as raw pixels   | Stored as Lossless WebP / PNG | Stored as Lossy WebP | Stored as S3TC, BPTC or ETC2 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                                          |
-+----------------+------------------------+-------------------------------+----------------------+------------------------------------------------------+
++------------------+-------------------------------+----------------------+------------------------------------------------------+------------------------+--------------------------------------+
+| Compress mode    | Lossless                      | Lossy                | VRAM Compressed                                      | VRAM Uncompressed      | Basis Universal                      |
++==================+===============================+======================+======================================================+========================+======================================+
+| **Description**  | Stored as Lossless WebP / PNG | Stored as Lossy WebP | Stored as S3TC, BPTC or ETC2 depending on platform   | Stored as raw pixels   | Transcoded to VRAM Compressed format |
++------------------+-------------------------------+----------------------+------------------------------------------------------+------------------------+--------------------------------------+
+| **Size on disk** | |regular| Small               | |good| Very small    | |regular| Small                                      | |bad| Large            | |good| Very small                    |
++------------------+-------------------------------+----------------------+------------------------------------------------------+------------------------+--------------------------------------+
+| **Memory usage** | |bad| Large                   | |bad| Large          | |good| Small                                         | |bad| Large            | |good| Small                         |
++------------------+-------------------------------+----------------------+------------------------------------------------------+------------------------+--------------------------------------+
+| **Performance**  | |regular| Normal              | |regular| Normal     | |good| Fast                                          | |regular| Normal       | |good| Fast                          |
++------------------+-------------------------------+----------------------+------------------------------------------------------+------------------------+--------------------------------------+
+| **Quality loss** | |good| None                   | |regular| Slight     | |bad| Moderate                                       | |good| None            | |bad| Moderate                       |
++------------------+-------------------------------+----------------------+------------------------------------------------------+------------------------+--------------------------------------+
+| **Load time**    | |bad| Slow                    | |bad| Slow           | |good| Fast                                          | |regular| Normal       | |regular| Normal                     |
++------------------+-------------------------------+----------------------+------------------------------------------------------+------------------------+--------------------------------------+
 
 .. |bad| image:: img/bad.png
 
@@ -102,121 +201,340 @@ advantages and disadvantages (|good| = best, |bad| = worst):
 
 .. |regular| image:: img/regular.png
 
-HDR Mode
-~~~~~~~~
+Estimated memory usage for a single RGBA8 texture with mipmaps enabled:
 
-Godot supports high dynamic range textures (as .HDR or .EXR). These are mostly useful as high dynamic range equirectangular panorama skies (the internet
-has plenty if you search for them), which replace Cubemaps in Godot 2.x. Modern PCs support the BC6H VRAM format, but there are still plenty that do not.
-
-If you want Godot to ensure full compatibility in terms of the 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 artifacts 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.
-
-Note that RGTC compression affects the resulting normal map image. You will have to adjust custom shaders that use the normal map to take this into account.
++---------------+---------------------+---------------------+---------------------+---------------------+---------------------+
+| Texture size  | Lossless            | Lossy               | VRAM Compressed     | VRAM Uncompressed   | Basis Universal     |
++===============+=====================+=====================+=====================+=====================+=====================+
+| **128×128**   | |good| 85 KiB       | |good| 85 KiB       | |good| 21 KiB       | |good| 85 KiB       | |good| 21 KiB       |
++---------------+---------------------+---------------------+---------------------+---------------------+---------------------+
+| **256×256**   | |good| 341 KiB      | |good| 341 KiB      | |good| 85 KiB       | |good| 341 KiB      | |good| 85 KiB       |
++---------------+---------------------+---------------------+---------------------+---------------------+---------------------+
+| **512×512**   | |good| 1.33 MiB     | |good| 1.33 MiB     | |good| 341 KiB      | |good| 1.33 MiB     | |good| 341 KiB      |
++---------------+---------------------+---------------------+---------------------+---------------------+---------------------+
+| **1024×1024** | |regular| 5.33 MiB  | |regular| 5.33 MiB  | |good| 1.33 MiB     | |regular| 5.33 MiB  | |good| 1.33 MiB     |
++---------------+---------------------+---------------------+---------------------+---------------------+---------------------+
+| **2048×2048** | |bad| 21.33 MiB     | |bad| 21.33 MiB     | |regular| 5.33 MiB  | |bad| 21.33 MiB     | |regular| 5.33 MiB  |
++---------------+---------------------+---------------------+---------------------+---------------------+---------------------+
+| **4096×4096** | |bad| 85.33 MiB     | |bad| 85.33 MiB     | |bad| 21.33 MiB     | |bad| 85.33 MiB     | |bad| 21.33 MiB     |
++---------------+---------------------+---------------------+---------------------+---------------------+---------------------+
 
 .. note::
 
-  Godot requires the normal map to use the X+, Y+ and Z+ coordinates, this is
-  known as OpenGL style. If you've imported a material made to be used with
-  another engine it may be DirectX style, in which case the normal map needs to
-  be converted so its Y axis is flipped.
+    In the above table, memory usage will be reduced by 25% for images that do
+    not have an alpha channel (RGB8). Memory usage will be further decreased by
+    25% for images that have mipmaps disabled.
+
+Notice how at larger resolutions, the impact of VRAM compression is much
+greater. With a 4:1 compression ratio (6:1 for opaque textures with S3TC), VRAM
+compression effectively allows a texture to be twice as large on each axis,
+while using the same amount of memory on the GPU.
+
+VRAM compression also reduces the memory bandwidth required to sample the
+texture, which can speed up rendering in memory bandwidth-constrained scenarios
+(which are frequent on integrated graphics and mobile). These factors combined
+make VRAM compression a must-have for 3D games with high-resolution textures.
+
+You can preview how much memory a texture takes by double-clicking it in the
+FileSystem dock, then looking at the Inspector:
+
+.. figure:: img/importing_images_inspector_preview.webp
+   :align: center
+   :alt: Previewing a texture in the Inspector
+
+   Previewing a texture in the Inspector. Credit: `Red Brick 03 - Poly Haven <https://polyhaven.com/a/red_brick_03>`__
+
+Compress > High Quality
+^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+    High-quality VRAM texture compression is only supported in the Forward+ and
+    Forward Mobile rendering methods.
+
+    When using the Compatibility rendering method, this option is always
+    considered disabled.
+
+If enabled, uses BPTC compression on desktop platforms and :abbr:`ASTC (Adaptive
+Scalable Texture Compression)` compression on mobile platforms. When using BPTC,
+BC7 is used for SDR textures and BC6H is used for HDR textures.
+
+If disabled (default), uses the faster but lower-quality S3TC compression on
+desktop platforms and ETC2 on mobile/web platforms. When using S3TC, DXT1 (BC1)
+is used for opaque textures and DXT5 (BC3) is used for transparent or normal map
+(:abbr:`RGTC (Red-Green Texture Compression)`) textures.
+
+BPTC and ASTC support VRAM compression for HDR textures, but S3TC and ETC2 do
+not (see **HDR Compression** below).
+
+Compress > HDR Compression
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. note::
+
+    This option only has an effect on textures that are imported as HDR formats in Godot
+    (``.hdr`` and ``.exr`` files).
+
+If set to **Disabled**, never uses VRAM compression for HDR textures, regardless
+of whether they're opaque or transparent. Instead, the texture is converted to
+RGBE9995 (9-bits per channel + 5-bit exponent = 32 bits per pixel) to reduce
+memory usage compared to a half-float or single-precision float image format.
+
+If set to **Opaque Only** (default), only uses VRAM compression for opaque HDR
+textures. This is due to a limitation of HDR formats, as there is no
+VRAM-compressed HDR format that supports transparency at the same time.
+
+If set to **Always**, will force VRAM compression even for HDR textures with an
+alpha channel. To perform this, the alpha channel is discarded on import.
+
+Compress > Normal Map
+^^^^^^^^^^^^^^^^^^^^^
+
+When using a texture as normal map, only the red and green channels are
+required. Given regular texture compression algorithms produce artifacts that
+don't look that nice in normal maps, the :abbr:`RGTC (Red-Green Texture Compression)`
+compression format is the best fit for this data. Forcing this option to **Enable**
+will make Godot import the image as :abbr:`RGTC (Red-Green Texture Compression)` compressed.
+By default, it's set to **Detect**. This means that if the texture is ever detected to
+be used as a normal map, it will be changed to **Enable** and reimported automatically.
+
+Note that :abbr:`RGTC (Red-Green Texture Compression)` compression affects the
+resulting normal map image. You will have to adjust custom shaders that use the
+normal map's blue channel to take this into account. Built-in material shaders
+already ignore the blue channel in a normal map (regardless of the actual normal
+map's contents).
+
+In the example below, the normal map with :abbr:`RGTC (Red-Green Texture Compression)`
+compression is able to preserve its detail much better, while
+using the same amount of memory as a standard RGBA VRAM-compressed texture:
+
+.. figure:: img/importing_images_normal_map_rgtc.webp
+   :align: center
+   :alt: Normal map with standard VRAM compression (left) and with RGTC VRAM compression (right)
+
+   Normal map with standard VRAM compression (left) and with RGTC VRAM compression (right)
+
+.. note::
+
+  Godot requires the normal map to use the X+, Y+ and Z+ coordinates, which is
+  known as an OpenGL-style normal map. If you've imported a material made to be
+  used with another engine, it may be DirectX-style. In this case, the normal map
+  needs to be converted by enabling the **Normal Map Invert Y** import option.
 
   More information about normal maps (including a coordinate order table for
   popular engines) can be found
   `here <http://wiki.polycount.com/wiki/Normal_Map_Technical_Details>`__.
 
-Flags
------
+Compress > Channel Pack
+^^^^^^^^^^^^^^^^^^^^^^^
 
-There are plenty of settings that can be toggled when importing an image as a texture, depending on the use case.
+If set to **sRGB Friendly** (default), prevents the RG color format from being
+used as it does not support sRGB color.
 
-Repeat
-~~~~~~
+If set to **Optimized**, allows the RG color format to be used if the texture
+does not use the blue channel.
 
-This setting is most commonly used in 3D, and is therefore generally disabled in 2D. It sets UV coordinates going beyond the 0,0 - 1,1 range to "loop".
+A third option **Normal Map (RG Channels)** is *only* available in layered
+textures (:ref:`class_Cubemap`, :ref:`class_CubemapArray`, :ref:`class_Texture2DArray`
+and :ref:`class_Texture3D`). This forces all layers from the texture to be imported
+with the RG color format to reduce memory usage, with only the red and green
+channels preserved. This only has an effect on textures with the **VRAM Compressed**
+or **Basis Universal** compression modes.
 
-Repeating can optionally be set to mirrored mode.
+Mipmaps > Generate
+^^^^^^^^^^^^^^^^^^
 
-Filter
-~~~~~~
+If enabled, smaller versions of the texture are generated on import. For
+example, a 64×64 texture will generate 6 mipmaps (32×32, 16×16, 8×8, 4×4, 2×2,
+1×1). This has several benefits:
 
-When pixels become larger than the screen pixels, this option enables 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.
+- Textures will not become grainy in the distance (in 3D), or if scaled down due
+  to camera zoom or CanvasItem scale (in 2D).
+- Performance will improve if the texture is displayed in the distance, since
+  sampling smaller versions of the original texture is faster and requires less
+  memory bandwidth.
 
-Mipmaps
-~~~~~~~
+The downside of mipmaps is that they increase memory usage by roughly 33%.
 
-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:
+It's recommended to enable mipmaps in 3D. However, in 2D, this should only be
+enabled if your project visibly benefits from having mipmaps enabled. If the
+camera never zooms out significantly, there won't be a benefit to enabling
+mipmaps but memory usage will increase.
 
-* 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 blurriness.
-
-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.
+Mipmaps > Limit
+^^^^^^^^^^^^^^^
 
 .. warning::
 
-    Since the texture will have its data modified when sRGB is enabled, this
-    means using the same texture in both 2D and 3D will make the texture
-    display with incorrect colors in either 2D or 3D.
+    **Mipmaps > Limit** is currently not implemented and has no effect when changed.
 
-    To work around this, make a copy of the texture on the filesystem and enable
-    sRGB on one of the copies only. Use the copy with sRGB enabled in 3D, and
-    the copy with sRGB disabled in 2D.
+If set to a value greater than ``-1``, limits the maximum number of mipmaps that
+can be generated. This can be decreased if you don't want textures to become too
+low-resolution at extreme distances, at the cost of some graininess.
 
-Process
--------
+Roughness > Mode
+^^^^^^^^^^^^^^^^
 
-Some special processes can be applied to images when imported as textures.
+The color channel to consider as a roughness map in this texture. Only effective if
+**Roughness > Src Normal** is not empty.
 
-Fix Alpha Border
-~~~~~~~~~~~~~~~~
+Rougness > Src Normal
+^^^^^^^^^^^^^^^^^^^^^
 
-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 like.
+The path to the texture to consider as a normal map for roughness filtering on
+import. Specifying this can help decrease specular aliasing slightly in 3D.
+
+Roughness filtering on import is only used in 3D rendering, not 2D.
+
+Process > Fix Alpha Border
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This puts pixels of the same surrounding color in transition from transparent to
+opaque areas. For textures displayed with bilinear filtering, this helps
+mitigate the outline effect when exporting images from an image editor.
 
 .. image:: img/fixedborder.png
 
-It's a good idea to leave it on by default, unless specific values are needed.
+It's recommended to leave this enabled (as it is by default), unless this causes
+issues for a particular image.
 
-Premultiplied Alpha
-~~~~~~~~~~~~~~~~~~~
+Process > Premult 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.
+An alternative to fixing darkened borders with **Fix Alpha Border** is to use
+premultiplied alpha. By enabling this option, the texture will be converted to
+this format. A premultiplied alpha texture requires specific materials to be
+displayed correctly:
 
-HDR as sRGB
-~~~~~~~~~~~
+- In 2D, a :ref:`class_CanvasItemMaterial` will need to be created and
+  configured to use the **Premul Alpha** blend mode on CanvasItems that use this
+  texture.
+- In 3D, there is no support for premultiplied alpha blend mode yet, so this
+  option is only suited for 2D.
 
-A few HDR files are broken and contain sRGB color data. It is advised not to use them, but, in the worst-case scenario, toggling this option on will make them look right.
+Process > Normal Map Invert Y
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Invert Color
-~~~~~~~~~~~~
+Godot requires the normal map to use the X+, Y+ and Z+ coordinates, which is
+known as an OpenGL-style normal map. If you've imported a material made to be
+used with another engine, it may be DirectX-style. In this case, the normal map
+needs to be converted by enabling the **Normal Map Invert Y** import option.
 
-Reverses the image's color. This is useful, for example, to convert a height map generated by external programs to depth map to use with :ref:`doc_standard_material_3d`.
+More information about normal maps (including a coordinate order table for
+popular engines) can be found
+`here <http://wiki.polycount.com/wiki/Normal_Map_Technical_Details>`__.
 
-Svg
----
+Process > HDR as sRGB
+^^^^^^^^^^^^^^^^^^^^^
 
-Scale
-~~~~~
+Some HDR images you can find online may be broken and contain sRGB color data
+(instead of linear color data). It is advised not to use those files. If you
+absolutely have to, enabling this option on will make them look correct.
 
-This option only applies to SVG files. It controls the scale of the SVG image. The default scale (1.0) will make the imported SVG match its original design scale.
+.. warning::
+
+    Enabling **HDR as sRGB** on well-formatted HDR images will cause the
+    resulting image to look too dark, so leave this disabled if unsure.
+
+Process > HDR Clamp Exposure
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Some HDR panorama images you can find online may contain extremely bright
+pixels, due to being taken from real life sources without any clipping.
+
+While these HDR panorama images are accurate to real life, this can cause the
+radiance map generated by Godot to contain sparkles when used as a background
+sky. This can be seen in material reflections (even on rough materials in
+extreme cases). Enabling **HDR Clamp Exposure** can resolve this using a smart
+clamping formula that does not introduce *visible* clipping – glow will keep
+working when looking at the background sky.
+
+Process > Size Limit
+^^^^^^^^^^^^^^^^^^^^
+
+If set to a value greater than ``0``, the size of the texture is limited on
+import to a value smaller than or equal to the value specified here. For
+non-square textures, the size limit affects the longer dimension, with the
+shorter dimension scaled to preserve aspect ratio. Resizing is performed using
+cubic interpolation.
+
+This can be used to reduce memory usage without affecting the source images, or
+avoid issues with textures not displaying on mobile/web platforms (as these
+usually can't display textures larger than 4096×4096).
+
+.. _doc_importing_images_detect_3d_compress_to:
+
+Detect 3D > Compress To
+^^^^^^^^^^^^^^^^^^^^^^^
+
+This changes the :ref:`doc_importing_images_compress_mode` option that is used
+when a texture is detected as being used in 3D.
+
+Changing this import option only has an effect if a texture is detected as being
+used in 3D. Changing this to **Disabled** then reimporting will not change the
+existing compress mode on a texture (if it's detected to be used in 3D), but
+choosing **VRAM Compressed** or **Basis Universal** will.
+
+Best practices
+--------------
+
+Supporting high-resolution texture sizes in 2D without artifacts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To support :ref:`multiple resolutions <doc_multiple_resolutions>` with crisp
+visuals at high resolutions, you will need to use high-resolution source images
+(suited for the highest resolution you wish to support without blurriness, which
+is typically 4K in modern desktop games).
+
+There are 2 ways to proceed:
+
+- Use a high base resolution in the project settings (such as 4K), then use the
+  textures at original scale. This is an easier approach.
+- Use a low base resolution in the project settings (such as 1080p), then
+  downscale textures when using them. This is often more difficult and can make
+  various calculations in script tedious, so the approach described above is
+  recommended instead.
+
+After doing this, you may notice that textures become grainy at lower viewport
+resolutions. To resolve this, enable **Mipmaps** on textures used in 2D in the
+Import dock. This will increase memory usage.
+
+Enabling mipmaps can also make textures appear blurrier, but you can choose
+to make textures sharper (at the cost of some graininess) by setting
+**Rendering > Textures > Default Filters > Texture Mipmap Bias** to a
+negative value.
+
+Use appropriate texture sizes in 3D
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+While there's no "one size fits all" recommendation, here are some general
+recommendations for choosing texture sizes in 3D:
+
+- The size of a texture should be adjusted to have a consistent texel density
+  compared to surrounding objects. While this cannot be ensured perfectly when
+  sticking to power-of-two texture sizes, it's usually possible to keep texture
+  detail fairly consistent throughout a 3D scene.
+- The smaller the object appears on screen, the smaller its texture should be.
+  For example, a tree that only appears in the background doesn't need a texture
+  resolution as high as other objects the player may be able to walk close to.
+- Using power-of-two texture sizes is recommended, but is not required. Textures
+  don't have to be square – sizes such as 1024×512 are acceptable.
+- There are diminishing returns to using large texture sizes, despite the
+  increased memory usage and loading times. Most modern 3D games not using a
+  pixel art style stick to 2048×2048 textures on average, with 1024×1024 and
+  512×512 for textures spanning smaller surfaces.
+- When working with physically-based materials in 3D, you can reduce memory
+  usage and file size without affecting quality too much by using a lower
+  resolution for certain texture maps. This works especially well for textures
+  that only feature low-frequency detail (such as a normal map for a snow
+  texture).
+
+If you have control over how the 3D models are created, these tips are also
+worth exploring:
+
+- When working with 3D models that are mostly symmetrical, you may be able to
+  use mirrored UVs to double the effective texel density. This may look
+  unnatural when used on human faces though.
+- When working with 3D models using a low-poly style and plain colors, you can
+  rely on vertex colors instead of textures to represent colors on the model's
+  surfaces.