Unit CastleTextureImages

Classes, Interfaces, Objects and Records

Types

Description

Handling of images for textures. This unit is not OpenGL-specific, it should be suitable for all 3D libraries. See CastleGLImage for OpenGL-specific handling of textures and other images.

Texture is any TEncodedImage instance. This includes not only a traditional 2D/3D matrix of pixels represented as TCastleImage, but also a texture compressed for GPU (TGPUCompressedImage). Moreover, a texture may have mipmaps defined — they are stored inside TCompositeImage instance (that contains a list of TEncodedImage).

Since not everything can really deal with such flexible definition of a texture, we decided to separate some routines specifically for textures. For example, you have LoadTextureImage to load full texture information — contrast this with LoadImage routine in CastleImages unit, that only returns TCastleImage (a "normal" way to deal with image data).

Uses

Generics.Collections
CastleImages
CastleInternalCompositeImage
CastleUtils
CastleVideos
CastleRenderOptions

Overview

Classes, Interfaces, Objects and Records

Name	Description
Class `TTexturesVideosCache`	A cache of loaded images for textures.

Functions and Procedures

function LoadTextureImage(const Url: String; out Composite: TCompositeImage; const LoadOptions: TLoadImageOptions = []): TEncodedImage; overload;

function LoadTextureImage(const Url: String; const LoadOptions: TLoadImageOptions = []): TEncodedImage; overload;

Constants

TextureImageClasses: array [0..3] of TEncodedImageClass = (
    TRGBImage,
    TRGBAlphaImage,
    TGrayscaleImage,
    TGrayscaleAlphaImage
  );

TextureImageClassesAll: array [0..8] of TEncodedImageClass = (
    
    TRGBImage,
    TRGBAlphaImage,
    TGrayscaleImage,
    TGrayscaleAlphaImage,

    
    TGPUCompressedImage,

    
    TGrayscaleFloatImage,
    TGrayscaleAlphaFloatImage,
    TRGBFloatImage,
    TRGBAlphaFloatImage
  );

minNearest = CastleRenderOptions.minNearest;

minLinear = CastleRenderOptions.minLinear;

minNearestMipmapNearest = CastleRenderOptions.minNearestMipmapNearest;

minNearestMipmapLinear = CastleRenderOptions.minNearestMipmapLinear;

minLinearMipmapNearest = CastleRenderOptions.minLinearMipmapNearest;

minLinearMipmapLinear = CastleRenderOptions.minLinearMipmapLinear;

minDefault = CastleRenderOptions.minDefault;

minFastest = CastleRenderOptions.minFastest;

minNicest = CastleRenderOptions.minNicest;

magNearest = CastleRenderOptions.magNearest;

magLinear = CastleRenderOptions.magLinear;

magDefault = CastleRenderOptions.magDefault;

magFastest = CastleRenderOptions.magFastest;

magNicest = CastleRenderOptions.magNicest;

DefaultSpriteSheetFramesPerSecond = 8.0;

Variables

LogTextureCache: boolean = false;

TextureCache: TTexturesVideosCache;

TextureLoadingScale: Cardinal = 1;

Description

Functions and Procedures

function LoadTextureImage(const Url: String; out Composite: TCompositeImage; const LoadOptions: TLoadImageOptions = []): TEncodedImage; overload;

Load image suitable for a texture. This will load image to memory formats supported by common 3D libraries (like OpenGL), for example it will never return TRGBFloatImage (although OpenGL may support it, but we cannot be sure at this point). It may return texture compressed using one of the GPU compression algorithms (see TTextureCompression).

If the image comes from a TCompositeImage file (DDS, KTX...), it will also return it (if not, Composite returned will be Nil). This allows you to e.g. use texture mipmaps recorded there. Note that Composite.OwnsFirstImage is set to False, so you can always safely free everything by simple FreeAndNil(Image); FreeAndNil(Composite);.

Overloaded version without Composite parameter assumes you're not interested in this information (still it handles Composite files of course, it just doesn't return Composite object instance).

function LoadTextureImage(const Url: String; const LoadOptions: TLoadImageOptions = []): TEncodedImage; overload;

This item has no description.

Constants

TextureImageClasses: array [0..3] of TEncodedImageClass = (
    TRGBImage,
    TRGBAlphaImage,
    TGrayscaleImage,
    TGrayscaleAlphaImage
  );

Image classes that are handled by absolutely all OpenGL versions.

TextureImageClassesAll: array [0..8] of TEncodedImageClass = (
    
    TRGBImage,
    TRGBAlphaImage,
    TGrayscaleImage,
    TGrayscaleAlphaImage,

    
    TGPUCompressedImage,

    
    TGrayscaleFloatImage,
    TGrayscaleAlphaFloatImage,
    TRGBFloatImage,
    TRGBAlphaFloatImage
  );

All image classes that may be handled by OpenGL. Some of them may require specific OpenGL extensions or versions (like GPU-compressed or float textures).

minNearest = CastleRenderOptions.minNearest;

We recommend using CastleRenderOptions unit to get these constants. But for backward compatibility, they are also available here.

minLinear = CastleRenderOptions.minLinear;

This item has no description.

minNearestMipmapNearest = CastleRenderOptions.minNearestMipmapNearest;

This item has no description.

minNearestMipmapLinear = CastleRenderOptions.minNearestMipmapLinear;

This item has no description.

minLinearMipmapNearest = CastleRenderOptions.minLinearMipmapNearest;

This item has no description.

minLinearMipmapLinear = CastleRenderOptions.minLinearMipmapLinear;

This item has no description.

minDefault = CastleRenderOptions.minDefault;

This item has no description.

minFastest = CastleRenderOptions.minFastest;

This item has no description.

minNicest = CastleRenderOptions.minNicest;

This item has no description.

magNearest = CastleRenderOptions.magNearest;

This item has no description.

magLinear = CastleRenderOptions.magLinear;

This item has no description.

magDefault = CastleRenderOptions.magDefault;

This item has no description.

magFastest = CastleRenderOptions.magFastest;

This item has no description.

magNicest = CastleRenderOptions.magNicest;

This item has no description.

DefaultSpriteSheetFramesPerSecond = 8.0;

Default frame per second for Sprite Sheet animations like Starling and Cocos2d.

Variables

LogTextureCache: boolean = false;

Log texture cache events. Allows to see how the cache performs, and also how alpha channel is detected. A lot of log messages.

Meaningful only if you initialized log (see CastleLog unit) by InitializeLog first.

TextureCache: TTexturesVideosCache;

Cache of texture images, equal to X3DCache and automatically initialized / finalized if you use X3DNodes unit.

TextureLoadingScale: Cardinal = 1;

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. 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_auto_generated_textures.php#section_texture_scale .

Each size (width, height, and (for 3D images) depth) is scaled by 1 / 2ˆ(TextureLoadingScale-1). 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.

Generated by PasDoc 0.16.0-snapshot.

API Reference

Unit CastleTextureImages

Description

Uses

Overview

Classes, Interfaces, Objects and Records

Functions and Procedures

Constants

Variables

Description

Functions and Procedures

Constants

Variables