Implement embedded texture (AiTexture)

Author: ctreffs

Sources/Assimp/AiTexture.swift

@@ -7,24 +7,91 @@
 
 import CAssimp
 
+/// Helper structure to describe an embedded texture
+///
+/// Normally textures are contained in external files but some file formats embed them directly in the model file.
+/// There are two types of embedded textures:
+/// 1. Uncompressed textures.
+/// The color data is given in an uncompressed format.
+/// 2. Compressed textures stored in a file format like png or jpg.
+/// The raw file bytes are given so the application must utilize an image decoder (e.g. DevIL) to get access to the actual color data.
+///
+/// Embedded textures are referenced from materials using strings like "*0", "*1", etc. as the texture paths (a single asterisk character followed by the zero-based index of the texture in the aiScene::mTextures array).
 public struct AiTexture {
     let texture: aiTexture
 
     public init(_ aiTexture: aiTexture) {
         texture = aiTexture
     }
 
-    var width: Int {
+    /// Texture original filename.
+    ///
+    /// Used to get the texture reference.
+    public var filename: String? {
+        String(aiString: texture.mFilename)
+    }
+
+    /// A hint from the loader to make it easier for applications
+    /// to determine the type of embedded textures.
+    ///
+    /// If mHeight != 0 this member is show how data is packed. Hint will consist of
+    /// two parts: channel order and channel bitness (count of the bits for every
+    /// color channel). For simple parsing by the viewer it's better to not omit
+    /// absent color channel and just use 0 for bitness. For example:
+    /// 1. Image contain RGBA and 8 bit per channel, achFormatHint == "rgba8888";
+    /// 2. Image contain ARGB and 8 bit per channel, achFormatHint == "argb8888";
+    /// 3. Image contain RGB and 5 bit for R and B channels and 6 bit for G channel, achFormatHint == "rgba5650";
+    /// 4. One color image with B channel and 1 bit for it, achFormatHint == "rgba0010";
+    /// If mHeight == 0 then achFormatHint is set set to '\\0\\0\\0\\0' if the loader has no additional
+    /// information about the texture file format used OR the
+    /// file extension of the format without a trailing dot. If there
+    /// are multiple file extensions for a format, the shortest
+    /// extension is chosen (JPEG maps to 'jpg', not to 'jpeg').
+    /// E.g. 'dds\\0', 'pcx\\0', 'jpg\\0'.  All characters are lower-case.
+    /// The fourth character will always be '\\0'.
+    public var achFormatHint: String {
+        CArray<CChar>.read(texture.achFormatHint) { body in
+            String(cString: body.baseAddress!)
+        }
+    }
+
+    /// Width of the texture, in pixels
+    ///
+    /// If mHeight is zero the texture is compressed in a format like JPEG.
+    /// In this case mWidth specifies the size of the memory area pcData is pointing to, in bytes.
+    public var width: Int {
         Int(texture.mWidth)
     }
 
-    var height: Int {
+    /// Height of the texture, in pixels
+    ///
+    /// If this value is zero, pcData points to a compressed texture in any format (e.g. JPEG).
+    public var height: Int {
         Int(texture.mHeight)
     }
 
-    var pcData: [aiTexel] {
-        [aiTexel](UnsafeMutableBufferPointer<aiTexel>(start: texture.pcData,
-                                                      count: width * height))
+    @inline(__always)
+    public var isCompressed: Bool {
+        height == 0
+    }
+
+    /// Data of the texture.
+    ///
+    /// Points to an array of mWidth * mHeight aiTexel's.
+    /// The format of the texture data is always ARGB8888 to make the implementation for user of the library as easy as possible.
+    /// If mHeight = 0 this is a pointer to a memory buffer of size mWidth containing the compressed texture data.
+    public var pcData: [aiTexel] {
+        let count: Int = height == 0 ? width : (width * height)
+        return [aiTexel](UnsafeMutableBufferPointer<aiTexel>(start: texture.pcData,
+                                                             count: count))
+    }
+
+    public var rawPcData: UnsafeBufferPointer<UInt8> {
+        let count: Int = height == 0 ? width : (width * height)
+        let length = MemoryLayout<aiTexel>.stride * count
+        return texture.pcData.withMemoryRebound(to: UInt8.self, capacity: length) { ptr in
+            UnsafeBufferPointer<UInt8>(start: ptr, count: length)
+        }
     }
 }