Unit CastleMaterialProperties

Material and texture properties, see TMaterialProperties. Set the URL property to load material properties from XML file.

Use the auto-generated alternative downscaled images. This allows to conserve both GPU memory and loading time by using a downscaled images versions.

The subset of your images which are affected by this must be declared inside the material_properties.xml file, which is loaded to MaterialProperties. And the image files must be prepared earlier by the build tool call "castle-engine auto-generate-textures". See the https://castle-engine.io/creating_data_material_properties.php#section_texture_scale .

Each size (width, height, and (for 3D images) depth) is scaled by 1 / 2ˆTextureLoadingScale. So value = 1 means no scaling, value = 2 means that each size is 1/2 (texture area is 1/4), value = 3 means that each size is 1/4 and so on.

This mechanism will not automatically downscale textures at runtime. If the downscaled texture version should exist, according to the material_properties.xml file, but it doesn't, then texture loading will simply fail. If you want to scale the texture at runtime, use the similar GLTextureScale instead.

This mechanism is independent from GLTextureScale:

• Scaling indicated by GLTextureScale is performed at runtime, after loading. It happens after the results of TextureLoadingScale have already been applied.

• The GLTextureScale works on a different subset of textures.

  For GLTextureScale, the usage of a texture determines if it's a GUI texture (which cannot be scaled) or not. So textures loaded through TDrawableImage, or declared as guiTexture in X3D, are not affected by GLTextureScale. All other textures are affected. It doesn't matter from where they are loaded – so it affects also texture contents created by code, or downloaded from the Internet.

  In contrast, the TextureLoadingScale works (only) on all the images declared as having a downscaled version in material_properties.xml. It is not affected by how the texture will be used.

• The GLTextureScale works only on texture formats that can be scaled. In particular, it cannot scale textures compressed with a GPU compression (S3TC and such). It silently ignores them.

  In contrast, the TextureLoadingScale can cooperate with GPU-compressed textures, if you also compress them automatically using the material_properties.xml and the build tool call "castle-engine auto-generate-textures". The downscaled image versions are generated from original (uncompressed, unscaled) images, and are then compressed.

• The GLTextureScale scaling is usually of worse quality, since it's done at runtime.

  In contrast, the downscaled textures used by TextureLoadingScale are generated as a preprocessing step. The build tool "castle-engine auto-generate-textures" may use a slower but higher-quality scaling.