Importing images and textures

Use Texture2D for an image displayed in UI, a sprite or a material. Use Image when CPU code needs pixels. The source file, imported texture and material sampler are different layers: changing one does not necessarily fix the others.

Import and display a PNG

1. Put a PNG at Images/plain.png in the project.
2. Select it in Content Browser. Keep the Texture2D importer, set compress/mode to Lossless for this first check, and apply Reimport.
3. Create a TextureRect and attach this complete ImagePreview.cs:

using Reckfell;

public partial class ImagePreview : TextureRect
{
    public override void _Ready()
    {
        Texture = ResourceLoader.Load<Texture2D>("asset://Images/plain.png");
        TextureFilter = TextureFilterEnum.Nearest;
        if (Texture == null)
            ReckfellApi.PushError("Cannot load asset://Images/plain.png");
    }
}

Start the level and give the TextureRect the required size. This example deliberately uses nearest filtering; choose linear filtering for smoothly scaled artwork. Load the original path rather than a generated cache filename. Reimport changes the playback resource without rewriting the original PNG.

Choose the resource and source format

For alpha-bearing raster art, use a format that actually stores alpha, such as PNG or WebP. JPEG does not supply an alpha channel. For HDR sources, use the HDR/EXR workflow rather than expecting PNG import to retain floating-point radiance. Format loaders and renderer support depend on the installed build: a recognized extension does not establish support for every variant, layered resource or GPU.

An ordinary SVG texture is rasterized at import time; svg/scale controls that size. Check the result of complex SVGs and convert text to paths for a portable vector asset. Editor theme-color conversion and editor-scale options are intended for editor icons, not general game-image color correction. Layered textures, HDR and SVG are source-reviewed here, not exercised by the PNG acceptance run.

Compression: separate disk size from GPU memory

VRAM format selection depends on platform, quality and channel settings. Do not assume one fixed compression ratio or that High Quality works identically on all renderers. Do not repeatedly recompress a damaged source: compare a lossless import with the original first.

For HDR, compress/hdr_compression can allow compression or discard alpha in Always mode. process/hdr_as_srgb is a correction for wrongly encoded HDR color, not a general brightness control. process/hdr_clamp_exposure changes extreme HDR values; evaluate reflections and exposure before using it to hide a lighting problem.

Filtering, repetition and color

Filter and repeat are configured on CanvasItem in 2D, on the material in 3D, or on sampler hints in a custom shader. They are not replacements for import settings.

• Nearest preserves distinct texels; linear blends neighboring texels. A mipmap filter also needs an imported mip chain.
• Repetition requires appropriate sampler settings and UVs. Excessive tiling or stretched UVs cannot be repaired by increasing texture resolution.
• Color maps and numeric maps have different roles. A custom color sampler uses source_color when it must convert source color to the rendering color space. Do not apply that conversion indiscriminately to normal, roughness or mask data.
• Check packed-map channel selection. Changing which channel a material reads differs from process/channel_remap, which rewrites imported channels.

The built-in material separates albedo/emission color textures from normal and scalar maps. Correct importer pixels alone do not prove correct shader color, exposure or map assignment.

Mipmaps and size

Enable mipmaps/generate when textures are viewed significantly smaller than their source size. A 32×16 fixture generates five lower-resolution levels down to 1×1. Mipmaps add storage; they do not increase base-image detail. Choose filters that use them and assess distant shimmer at the actual viewing scale.

Known current limitation: mipmaps/limit does not truncate the loaded chain. The native check sets it to 2 and still reads five levels. Do not use this parameter as a working memory budget control.

process/size_limit reduces the longest dimension and scales the other to preserve aspect ratio. In the test, 32×16 becomes 8×4 at limit 8; the original remains 32×16. This reduces actual image detail. Choose the limit from screen coverage and texel density, not a universal “every platform supports 4K” rule.

Detect 3D can enable mipmaps and change compression after a texture is used in 3D. Check the resulting Import parameters when appearance changes. Disabling detection does not automatically restore every previously changed parameter.

Alpha and normal maps

For premultiplied textures, select the corresponding blend mode on CanvasItemMaterial/BaseMaterial3D or use blend_premul_alpha in a matching custom shader. A mismatched blend convention can produce dark or bright edges. Normal Y inversion does not flip the image vertically and should not be used as a general color correction.

For cutout foliage, verify both source alpha and the material's transparency mode/cutoff. A PNG with alpha can still appear as a solid rectangle under an opaque material. For alpha-tested mipmaps, preserve_alpha_test_coverage and its threshold are separate from the material cutoff; judge the distant silhouette. For roughness filtering, roughness/mode selects a channel and roughness/src_normal supplies the associated normal image; this processing requires mipmaps.

CPU access and export

Texture2D.GetImage returns an Image copy and can require GPU readback. Changing that copy does not update the existing texture. For repeated access, retain the CPU image or use a deliberate update workflow instead of reading back every frame.

Image.LoadFromFile reads original bytes and bypasses import transformations. The test sees the original 32×16 source while the imported texture is 8×4. For a project asset, the runtime warns that this raw loading path is not a reliable export workflow. Import as Image and load it as a resource when CPU access to a packaged asset is required, or explicitly package/manage the raw file. Do not infer exported-file availability from editor execution.

Diagnose a defect

The native run verifies actual PNG import and Vulkan readback for lossless/raw pixels, resizing, mipmaps, premultiplication, edge RGB, channel operations and the exact C# example. It records the expected raw-file export warning. It does not establish sampled shader color, visual edge quality, HDR/Basis/VRAM/SVG behavior, layered imports, alpha-coverage filtering, all GPUs or exported builds.