Khronos Image (KMG) File Format Specification

Version 1.0.0 draft, 9 September 2015

This version:

https://www.khronos.org/opengles/sdk/tools/KMG/1.0/

Latest version:

https://www.khronos.org/opengles/sdk/tools/KMG/1.0/

Previous version:

https://www.khronos.org/opengles/sdk/tools/KTX/file_format_spec/

Editor:

Christophe Riccio (Unity)

Abstract

KMG is a standard graphics API independent container file format for storing textures used by GPUs.

Motivations

• KTX depends on OpenGL and OpenGL ES
• KTX doesn't distinguish OpenGL profiles
• KTX doesn't support texture swizzle
• KTX doesn't explicitly export texture target, no texture rectangle support
• KTX doesn't support texture formats from others graphics APIs than OpenGL
• KTX doesn't make it easy to load only a subset of layers
• KTX doesn't store faces continuously in memory

All these issues have been addressed by KMG file format.

Status of this document

Proposal draft.

Table of contents

File Structure

Byte[12] Identifier
UInt32 Endianness
UInt32 Target
UInt32 Format
UInt32 SwizzleRed
UInt32 SwizzleGreen
UInt32 SwizzleBlue
Uint32 SwizzleAlpha
UInt32 PixelWidth
UInt32 PixelHeight
UInt32 PixelDepth
UInt32 Layers
UInt32 Levels
UInt32 Faces
UInt32 GenerateMipmaps
UInt32 BaseLevel
UInt32 MaxLevel

for each Layer in Layers
  for each Level in Levels
     for each Face in Faces
         for each Depth in PixelDepth
             for each row or RowOfBlocks in PixelHeight
                 for each pixel or BlockOfPixels in PixelWidth
                     Byte data[format-specific-number-of-bytes]
                 end
             end
         end
     end
  end
end

Field Descriptions

Identifier

The file identifier is a unique set of bytes that will differentiate the file from other types of files. It consists of 12 bytes, as follows:

Byte[12] FileIdentifier = {
   0xAB, 0x4B, 0x4D, 0x4A, 0x31, 0x30, 0x30, 0xBB, 0x0D, 0x0A, 0x1A, 0x0A
}

This can also be expressed using C-style character definitions as:

Byte[12] FileIdentifier = {
    '«', 'K', 'M', 'G', '1', '0', '0', '»', '\r', '\n', '\x1A', '\n'
}

The rationale behind the choice values in the identifier is based on the rationale for the identifier in the PNG specification. This identifier both identifies the file as a KMG file and provides for immediate detection of common file-transfer problems.

• Byte [0] is chosen as a non-ASCII value to reduce the probability that a text file may be misrecognized as a KMG file.
• Byte [0] also catches bad file transfers that clear bit 7.
• Bytes [1..6] identify the format, and are the ascii values for the string "KMG100".
• Byte [7] is for aesthetic balance with byte 1 (they are a matching pair of double-angle quotation marks).
• Bytes [8..9] form a CR-LF sequence which catches bad file transfers that alter newline sequences.
• Byte [10] is a control-Z character, which stops file display under MS-DOS, and further reduces the chance that a text file will be falsely recognised.
• Byte [11] is a final line feed, which checks for the inverse of the CR-LF translation problem.

Endianness

Endianness contains the number 0x04030201 written as a 32 bit integer. If the file is little endian then this is represented as the bytes 0x01 0x02 0x03 0x04. If the file is big endian then this is represented as the bytes 0x04 0x03 0x02 0x01. When reading endianness as a 32 bit integer produces the value 0x04030201 then the endianness of the file matches the endianness of the program that is reading the file and no conversion is necessary. When reading endianness as a 32 bit integer produces the value 0x01020304 then the endianness of the file is opposite the endianness of the program that is reading the file, and in that case the program reading the file must endian convert all header bytes to the endianness of the program (i.e. a little endian program must convert from big endian, and a big endian program must convert to little endian).

Target

Target must be one of the following values:

Format

Format must be one of the following values:

The per block storage for compressed formats is described in reference documents.

The channels exposed by the formats are exposed using the following letters:

• R: Red channel.
• G: Green channel.
• B: Blue channel.
• A: Alpha channel.
• D: Depth channel.
• S: Stencil channel.
• L: Luminance channel. When converted to RGB, the channel value is copied to each RGB component.
• X: Memory padding, eg: BGR 8 bits per channel stored in 32 bits where 8 bits are meant to be ignored.

The order of the components in the formats follows the order of the component in memory.

The following postfixs are used to describ properties of the format:

• UNORM: Unsigned integer data sampled with border values clamped as unsigned normalized float
• SNORM: Signed integer data sampled with border values clamped as signed normalized float
• USCALE: Unsigned integer data sampled with border values clamped as unsigned scaled float
• SSCALE: Signed integer data sampled with border values clamped as signed scaled float
• UINT: Unsigned integer data sampled as unsigned integer
• SINT: Signed integer data sampled as signed integer
• UFLOAT: Floating point value without signed bit data
• SFLOAT: Floating point value data
• SRGB: Standardized non-linear unsigned integer data with roughly a 2.2 gamma correction data (IEC 61966-2-1) sampled with border values clamped as unsigned normalized float

SwizzleRed, SwizzleGreen, SwizzleBlue, SwizzleAlpha

Swizzle is a mechanism to swizzle the components of a texture before they are applied as they are returned to the shader. SwizzleRed, SwizzleGreen, SwizzleBlue and SwizzleAlpha must take one of the following values:

The first swizzle parameter affects the first component of Cs as:

    if (SwizzleRed == SWIZZLE_RED) {
        TexelDestination[0] = TexelSource[0];
    } else if (SwizzleRed == SWIZZLE_GREEN) {
        TexelDestination[0] = TexelSource[1];
    } else if (SwizzleRed == SWIZZLE_BLUE) {
        TexelDestination[0] = TexelSource[2];
    } else if (SwizzleRed == SWIZZLE_ALPHA) {
        TexelDestination[0] = TexelSource[3];
    } else if (SwizzleRed == SWIZZLE_ZERO) {
        TexelDestination[0] = 0;
    } else if (SwizzleRed == SWIZZLE_ONE) {
        TexelDestination[0] = 1; // float or int depending on texture component type
    }

    and similarly for the other components.

PixelWidth, PixelHeight, PixelDepth

The size of the texture image for level 0, in pixels. No rounding to block sizes should be applied for block compressed textures.

For 1D textures PixelHeight and PixelDepth must be 1. For 2D and cube textures PixelDepth must be 1.

Layers

Layers specifies the number of layers in a texture array. The minimum value is 1.

Levels

Levels must equal 1 for non-mipmapped textures. For mipmapped textures, it equals the number of mipmaps. Mipmaps are stored in order from largest size to smallest size. The first mipmap level is always level 0. A KMG file does not need to contain a complete mipmap pyramid. If Levels equals 0, it indicates that a full mipmap pyramid should be generated from level 0 at load time (this is usually not allowed for compressed formats).

Faces

Faces specifies the number of cubemap faces. For cubemaps and cubemap arrays this should be 6. For non cubemaps this should be 1. Cube map faces are stored in the order: +X, -X, +Y, -Y, +Z, -Z.

GenerateMipmaps

Mipmap generation replaces texel image levels baselevel + 1 through q with images derived from the baselevel image, regardless of their previous contents. All other mimap images, including the baselevel + 1 image, are left unchanged by this computation.

The internal formats of the derived mipmap images all match those of the baselevel image. The contents of the derived images are computed by repeated, filtered reduction of the baselevel + 1 image. For one- and two-dimensional array and cube map array textures, each layer is filtered independently.

If the texture format is compressed, GenerateMipmaps must be FILTER_NONE.

BaseLevel

Specifies the index of the lowest defined mipmap level. The minimum value is 0. The maximum value is log2(max(width, height, depth)) + 1. BaseLevel must be lower or equal to MaxLevel.

MaxLevel

Sets the index of the highest defined mipmap level. This is an integer value. The minimum value is 0. The maximum value is log2(max(width, height, depth)) + 1. BaseLevel must be lower or equal to MaxLevel.

General comments

The unpack alignment is 4. I.e. uncompressed pixel data is packed according to the rules described in section 8.4.4.1 of the OpenGL 4.4 specification [OPENGL44] for a GL_UNPACK_ALIGNMENT of 4.

Values listed in tables referred to in the OpenGL 4.4 specification [OPENGL44] may be supplemented by extensions. The references are given as examples and do not imply that all of those texture types can be loaded in OpenGL ES or earlier versions of OpenGL.

Texture data in a KMG file are arranged so that the first pixel in the data stream for each face and/or array element is closest to the origin of the texture coordinate system. In OpenGL that origin is conventionally described as being at the lower left, but this convention is not shared by all image file formats and content creation tools, so there is abundant room for confusion.

The desired texture axis orientation is often predetermined by, e.g. a content creation tool's or existing application's use of the image. Therefore it is strongly recommended that tools for generating KMG files clearly describe their behaviour, and provide an option to specify the texture axis origin and orientation relative to the logical orientation of the source image. At minimum they should provide a choice between top-left and bottom-left as origin for 2D source images, with the positive S axis pointing right. Where possible, the preferred default is to use the logical upper-left corner of the image as the texture origin. Note that this is contrary to the standard interpretation of GL texture coordinates. However, the majority of texture compression tools use this convention.

As an aid to writing image manipulation tools and viewers, the logical orientation of the data in a KMG file may be indicated in the file's key/value metadata. Note that this metadata affects only the logical interpretation of the data, has no effect on the mapping from pixels in the file byte stream to texture coordinates. The recommended key to use is:

• KMGorientation

It is recommended that viewing and editing tools support at least the following values:

• S=r,T=d
• S=r,T=u
• S=r,T=d,R=i
• S=r,T=u,R=o

where

• S indicates the direction of increasing S values
• T indicates the direction of increasing T values
• R indicates the direction of increasing R values
• r indicates increasing to the right
• l indicates increasing to the left
• d indicates increasing downwards
• u indicates increasing upwards
• o indicates increasing out from the screen (moving towards viewer)
• i indicates increasing in towards the screen (moving away from viewer)

Although other orientations can be represented, it is recommended that tools that create KMG files use only the values listed above as other values may not be widely supported by other tools.

An example KMG 1.0 file:

// HEADER
0xAB, 0x4B, 0x54, 0x58, // first four bytes of Byte[12] identifier
0x20, 0x32, 0x30, 0xBB, // next four bytes of Byte[12] identifier
0x0D, 0x0A, 0x1A, 0x0A. // final four bytes of Byte[12] identifier
0x04, 0x03, 0x02, 0x01, // Byte[4] endianness (Big endian in this case)
0x00, 0x00, 0x00, 0x02, // UInt32 Target = TARGET_2D
0x00, 0x00, 0x00, 0x24, // UInt32 Format = FORMAT_RGBA8_SRGB
0x00, 0x00, 0x00, 0x00, // UInt32 SwizzleRed = SWIZZLE_RED
0x00, 0x00, 0x8D, 0x64, // UInt32 SwizzleGreen = SWIZZLE_GREEN
0x00, 0x00, 0x19, 0x07, // UInt32 SwizzleBlue = SWIZZLE_BLUE
0x00, 0x00, 0x19, 0x07, // UInt32 SwizzleAlpha = SWIZZLE_ALPHA
0x00, 0x00, 0x00, 0x20, // UInt32 PixelWidth = 32
0x00, 0x00, 0x00, 0x20, // UInt32 PixelHeight = 32
0x00, 0x00, 0x00, 0x00, // UInt32 PixelDepth = 1
0x00, 0x00, 0x00, 0x00, // UInt32 Layers = 1
0x00, 0x00, 0x00, 0x01, // UInt32 Faces = 1
0x00, 0x00, 0x00, 0x01, // UInt32 Levels = 1
0x00, 0x00, 0x00, 0x00, // UInt32 GenerateMipmaps = FILTER_NONE
// TEXTURE DATA
0xD8, 0xD8, 0xD8, 0xDA, // Byte[512] RGBA8 texture data...
...

IANA Mime-Type Registration Information

Permission is expressly granted to IANA to copy this section as necessary for managing the MIME types registry.

Type name: Image

Subtype name: kmg

Required parameters: none

Optional parameters: none

Encoding considerations: binary

Security considerations:

The kmg type is a binary data stream which contains no executable code that could disrupt a client processor. There is no provision in the type specification that would allow authors to insert executable code that would present any security risk to a client machine.

Because every item's length is available at its beginning, there is robust defense against corrupted or fraudulent data that might overflow a decoder's buffer. Also the signature bytes provide early detection of common file transmission errors.

The kmg type may contain texture data compressed using OpenGL standard or vendor-specific schemes. These compression schemes are designed so small blocks of data (typically around 64 bits) can be decompressed in real time into a small block of pixels (typically 4x4) during texel fetch. In such schemes it is not possible for a small amount of data to expand enormously because the level of compression is limited; the compressed size is related directly to the number of pixels in the uncompressed image and not to the content of the data.

The kmg type does not provide encryption of the data payload. Users or applications wishing or needing to keep their images confidential must overlay their own encryption on the kmg data during transmission.

Interoperability considerations:

The kmg type includes a field identifying the endianness of the machine which created the data. Applications reading the data are expected to check this field and convert the endianness, if necessary. The texture data payload may be compressed using an OpenGL-vendor-specific scheme. In this case, only devices or applications having a matching decompressor will be able to display the data. The compression scheme is identified in the kmg data so applications can quickly reject data using unsupported schemes.

References

[S3TC]

GL_EXT_texture_compression_s3tc, Pat Brown, Slawomir Grajewski, July 2013.

[S3TC_SRGB]

GL_EXT_texture_sRGB, Mark J. Kilgard, January 2007.

[RGTC]

GL_ARB_texture_compression_rgtc, Mark J. Kilgard, January 2015.

[BPTC]

GL_ARB_texture_compression_bptc, Eric Werness, Piers Daniell, January 2011.

[ETC1]

GL_OES_compressed_ETC1_RGB8_texture, Jacob Strom, April 2008.

[ETC2]

GL_ARB_ES3_compatibility, Piers Daniell, October 2013.

[ASTC]

GL_KHR_texture_compression_astc_hdr, Sean Ellis, Jon Leech, September 2012.

[PVRTC1]

GL_IMG_texture_compression_pvrtc, Graham Connor, June 2012.

[PVRTC2]

GL_IMG_texture_compression_pvrtc2, Ben Bowman, December 2012.

[PVRTC_SRGB]

GL_EXT_pvrtc_sRGB, Benj Lipchak, June 2013.

[ATC]

GL_AMD_compressed_ATC_texture, Maurice Ribble, February 2008.

Acknowledgements

Revision History

2015-09-09

Initial draft

License