Class TCompositeImage

Unit

Declaration

type TCompositeImage = class(TObject)

Description

Composite image file (like KTX or DDS). This supports image that can have mipmaps, can be 3D, and can be a cubemap. This is something more than our TCastleImage (or TEncodedImage), which can only be a single pixel matrix (it can be 3D, but it cannot be a cubemap or have mipmaps).

In essence, this is a container for a sequence of simple images in the Images property. The interpretation of the image sequence depends on other fields: first of all CompositeType and Mipmaps.

The basic usage of this class is to load a file using LoadFromFile or LoadFromStream.

Note that you can write (change) many properties of this class. This allows you to create, or load and edit, composite files. You can even later save the composite image back to the stream (like a file) by SaveToStream or SaveToFile. Be careful though: you're responsible then to set all properties to sensible values. For example, the length (and interpretation) of Images list is determined by other properties of this class, so be sure to set them all to something sensible.

Hierarchy

  • TObject
  • TCompositeImage

Overview

Nested Types

Published TDDSCubeMapSide = (...);

Fields

Public class var AutomaticCompression: boolean;
Public class var AutomaticCompressionType: TTextureCompression;

Methods

Public constructor Create;
Public destructor Destroy; override;
Public function CubeMapImage(const Side: TCubeMapSide; const Level: Cardinal = 0): TEncodedImage;
Public procedure LoadFromStream(Stream: TStream; const URL: string; MimeType: string = ''; const Options: TLoadImageOptions = []);
Public procedure LoadFromFile(URL: string; const Options: TLoadImageOptions = []);
Public procedure SaveToStream(Stream: TStream; const MimeType: string);
Public procedure SaveToFile(const URL: string);
Public procedure Close;
Public procedure Flatten3d;
Public procedure DecompressTexture;
Public class function MatchesURL(URL: string): boolean;
Public procedure AddCubeMapImages(const AImages: TCubeMapImages);

Properties

Public property Images: TEncodedImageList read FImages;
Public property Width: Cardinal read FWidth write FWidth;
Public property Height: Cardinal read FHeight write FHeight;
Public property CompositeType: TCompositeType read FCompositeType write FCompositeType;
Public property Mipmaps: boolean read FMipmaps write FMipmaps;
Public property MipmapsCount: Cardinal read FMipmapsCount write FMipmapsCount;
Public property CubeMapSides: TCubeMapSides read GetCubeMapSides write SetCubeMapSides;
Public property Depth: Cardinal read FDepth write FDepth;
Public property OwnsFirstImage: boolean read FOwnsFirstImage write FOwnsFirstImage default true;

Description

Nested Types

Published TDDSCubeMapSide = (...);

DDS cube map sides.

Compared with TCubeMapSide type, the meaning positive/negative Y faces is swapped.

Reason: Cube map sides are named and written in DDS file in a way natural for DirectX, and DirectX has left-handed coordinate system, which means that one axis seems reverted when you want OpenGL right-handed coord system (like OpenGL, see http://opengl.org/registry/specs/ARB/texture_cube_map.txt). See [https://castle-engine.io/x3d_implementation_status.php#section_dds] for more.

Values
  • dcsPositiveX
  • dcsNegativeX
  • dcsPositiveY
  • dcsNegativeY
  • dcsPositiveZ
  • dcsNegativeZ

Fields

Public class var AutomaticCompression: boolean;

Some DDS files specify unknown GPU texture compression. More precisely, the DxgiFormat is equal DXGI_FORMAT_UNKNOWN (see https://msdn.microsoft.com/en-us/library/windows/desktop/bb173059(v=vs.85).aspx ). This can happen if you used PvrTexTool and compressed to PVRTC2_* formats.

To be able to read such DDS files anyway, set AutomaticCompression to true and set AutomaticCompressionType as appropriate.

Public class var AutomaticCompressionType: TTextureCompression;
 

Methods

Public constructor Create;
 
Public destructor Destroy; override;
 
Public function CubeMapImage(const Side: TCubeMapSide; const Level: Cardinal = 0): TEncodedImage;

Return given side of cube map. Assumes CompositeType = ctCubeMap and CubeMapSides = all.

Level is mipmap level. Pass 0 for base level. When not Mipmaps, Level must be 0.

Public procedure LoadFromStream(Stream: TStream; const URL: string; MimeType: string = ''; const Options: TLoadImageOptions = []);

Load composite (KTX or DDS) image from any TStream. The image type is recognized from the MimeType extension, or (if empty) from URL, so make sure that you provide at least one of these parameters.

Exceptions raised
EInvalidCompositeImage
In case of any error in the file data.
Public procedure LoadFromFile(URL: string; const Options: TLoadImageOptions = []);

Load composite (KTX or DDS) image from this URL.

Public procedure SaveToStream(Stream: TStream; const MimeType: string);
 
Public procedure SaveToFile(const URL: string);
 
Public procedure Close;

Close all loaded image data. Effectively, this releases all data loaded by LoadFromStream, reverting the object to the state right after creation.

Public procedure Flatten3d;

Convert 3D images in Images list into a sequences of 2D images. Useful utility for 3d (volume) textures.

Normal loading of 3D composite textures creates single TCastleImage (using Depth possibly > 1) for each mipmap level. Such TCastleImage with depth is comfortable if you want to load this 3d texture into OpenGL (as then the image data is just a continuous memory area, loadable by glTexImage3d). But it's not comfortable if you want to display it using some 2D GUI. For example, it's not comfortable for image viewer like castle-view-image.

So this method will convert such TCastleImage instances (with Depth > 1) into a sequence of TCastleImage instances all with Depth = 1. This isn't difficult, memory contents on 3d TCastleImage may be splitted into many 2d TCastleImage instances without problems.

Note that it's safe to do this before saving the image. SaveToFile/SaveToStream methods accept both layouts of images (because, as said, memory contents actually are the same before and after splitting).

Note that this may free all Images (possibly even whole Images object), disregarding OwnsFirstImage (as it would be difficult, since it may or may not replace it with new images).

Public procedure DecompressTexture;

Decompress texture images (if any) on the Images list, replacing them with uncompressed equivalents. This can be used to decompress textures compressed using GPU compression algorithms, see TTextureCompression. See TGPUCompressedImage.Decompress.

Just like Flatten3d: Note that this may free all Images (possibly even whole Images object), disregarding OwnsFirstImage (as it would be difficult, since it may or may not replace it with new images).

Exceptions raised
ECannotDecompressTexture
If some image cannot be decompressed for any reason.
Public class function MatchesURL(URL: string): boolean;

Does this URL look like it contains composite (KTX, DDS...) contents. Guesses by processing the URL with ProcessImageUrl and then looking at final filename extension.

Public procedure AddCubeMapImages(const AImages: TCubeMapImages);
 

Properties

Public property Images: TEncodedImageList read FImages;

Images sequence stored in this composite file.

This has always length > 0 when file is successfully loaded (that is, when LoadFromStream method finished without raising any exception).

Public property Width: Cardinal read FWidth write FWidth;
 
Public property Height: Cardinal read FHeight write FHeight;
 
Public property CompositeType: TCompositeType read FCompositeType write FCompositeType;
 
Public property Mipmaps: boolean read FMipmaps write FMipmaps;

Does this composite image contain mipmaps. If True, then all Images are guaranteed to have sizes being power of 2.

Public property MipmapsCount: Cardinal read FMipmapsCount write FMipmapsCount;

Mipmaps count. Always 1 when Mipmaps = False, this is usually comfortable.

Public property CubeMapSides: TCubeMapSides read GetCubeMapSides write SetCubeMapSides;

Present cube map sides. Valid only when image is loaded and is ctCubeMap.

Public property Depth: Cardinal read FDepth write FDepth;

Depth of volume (3D) texture. Always 1 when CompositeType is not ctVolume, this is usually comfortable.

Public property OwnsFirstImage: boolean read FOwnsFirstImage write FOwnsFirstImage default true;

When False, then closing this composite image will not free Images[0]. Closing happens when you call the Close method or destructor of this object. When this is False, you're responsible to storing and freeing Images[0] later yourself, or you'll get memory leaks.


Generated by PasDoc 0.15.0.