Castle Game Engine: CastleDDS: Class TDDSImage

# Class TDDSImage
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleDDS ## Declaration `type TDDSImage = class(TObject)` ## Description DDS image file. Basically, DDS is just a sequence of images (in the Images property). The interpretation of the image sequence depends on other fields: first of all DDSType and Mipmaps. The basic usage of this class is to load a DDS file: see LoadFromFile, LoadFromStream. Note that you can write (change) many properties of this class. This allows you to create, or load and edit, DDS files. You can even later save the DDS 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 TDDSImage ## Overview ### Fields
| `classvar AutomaticCompression: boolean;`
| `classvar AutomaticCompressionType: TGPUCompression;`
### Methods
| `constructor Create;`
| `destructor Destroy; override;`
| `function CubeMapImage(const Side: TDDSCubeMapSide; const Level: Cardinal = 0): TEncodedImage;`
| `procedure LoadFromStream(Stream: TStream);`
| `procedure LoadFromFile(const URL: string);`
| `procedure SaveToStream(Stream: TStream);`
| `procedure SaveToFile(const URL: string);`
| `procedure Close;`
| `procedure Flatten3d;`
| `procedure DecompressTexture;`
| `class function MatchesURL(const URL: string): boolean;`
### Properties
| `property Images: TEncodedImageList read FImages;`
| `property Width: Cardinal read FWidth write FWidth;`
| `property Height: Cardinal read FHeight write FHeight;`
| `property DDSType: TDDSType read FDDSType write FDDSType;`
| `property Mipmaps: boolean read FMipmaps write FMipmaps;`
| `property MipmapsCount: Cardinal read FMipmapsCount write FMipmapsCount;`
| `property CubeMapSides: TDDSCubeMapSides read FCubeMapSides write FCubeMapSides;`
| `property Depth: Cardinal read FDepth write FDepth;`
| `property OwnsFirstImage: boolean read FOwnsFirstImage write FOwnsFirstImage default true;`
## Description ### Fields
| `classvar AutomaticCompression: boolean;`
Some DDS files specify unknown GPU texture compression. To read them, set this to true and set AutomaticCompressionType.
| `classvar AutomaticCompressionType: TGPUCompression;`
### Methods
| `constructor Create;`
| `destructor Destroy; override;`
| `function CubeMapImage(const Side: TDDSCubeMapSide; const Level: Cardinal = 0): TEncodedImage;`
Return given side of cube map. Assumes DDSType = dtCubeMap and CubeMapSides = all. Level is mipmap level. Pass 0 for base level. When not Mipmaps, Level must be 0.
| `procedure LoadFromStream(Stream: TStream);`
Load DDS image from any TStream. ###### Exceptions raised EInvalidDDS In case of any error in the file data.
| `procedure LoadFromFile(const URL: string);`
| `procedure SaveToStream(Stream: TStream);`
| `procedure SaveToFile(const URL: string);`
| `procedure Close;`
Close all loaded image data. Effectively, this releases all data loaded by LoadFromStream, reverting the object to the state right after creation.
| `procedure Flatten3d;`
Convert 3D images in Images list into a sequences of 2D images. Useful utility for 3d (volume) textures. Normal loading of 3d DDS 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 continous 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 glViewImage. 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).
| `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 TGPUCompression. 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.
| `class function MatchesURL(const URL: string): boolean;`
Does this URL look like it contains DDS contents. Guesses looking at filename extension.
### Properties
| `property Images: TEncodedImageList read FImages;`
Images sequence stored in this DDS file. This has always length > 0 when DDS is successfully loaded (that is, when LoadFromStream method finished without raising any exception).
| `property Width: Cardinal read FWidth write FWidth;`
| `property Height: Cardinal read FHeight write FHeight;`
| `property DDSType: TDDSType read FDDSType write FDDSType;`
| `property Mipmaps: boolean read FMipmaps write FMipmaps;`
Does this DDS file contain mipmaps. If `True`, then all Images are guaranteed to have sizes being power of 2.
| `property MipmapsCount: Cardinal read FMipmapsCount write FMipmapsCount;`
Mipmaps count. Always 1 when Mipmaps = `False`, this is usually comfortable.
| `property CubeMapSides: TDDSCubeMapSides read FCubeMapSides write FCubeMapSides;`
Present cube map sides. Valid only when image is loaded and is dtCubeMap.
| `property Depth: Cardinal read FDepth write FDepth;`
Depth of volume (3D) texture. Always 1 when DDSType is not dtVolume, this is usually comfortable.
| `property OwnsFirstImage: boolean read FOwnsFirstImage write FOwnsFirstImage default true;`
When `False`, then closing this DDS 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.13.0 on 2015-06-15 04:43:09