cl ktx2

1.0.0

An implementation of the Khronos KTX Version 2 image file format

Table of Contents

About cl-ktx2

This is an implementation of the Khronos KTX2 image file format.

How To

Load the cl-ktx2 library, and invoke read-file to read a file from any of the supported binary-structures backends.

The returned structure can be easily accessed. Since the image data is already pre-packed for upload to the GPU, you should be able to just iterate over the level-images and upload via gl-tex-image-2d etc. Note that the gl-* functions return the direct enum integers that you can pass to the relevant functions.

The documentation on some of the fields, especially when dealing with the data format descriptors, is a bit sparse in this library. This is because these concepts are very complicated, and I'd just be repeating what the Khronos specifications say in other words, so please instead refer to the KTX2 Specification and the Khronos Data Format Specification for expanded descriptions on the various fields and data bits.

Note that this library does currently not implement any compression or encoding schemes that the format can contain. As such it is up to you to ensure that the data is interpreted and decoded in the correct way. Cl-ktx2 will simply hand you an opaque octet vector of the data. The same goes for creating files. If you want to create compressed image data, you will likely want to rely on tools like Khronos' own ktx-software, or Kram instead.

If you really want to use a pure Lisp workflow, please contribute the encoding and decoding algorithms :)

System Information

Version: 1.0.0

Dependencies:

Author: Yukari Hafner

License: zlib

Homepage: https://shinmera.com/docs/cl-ktx2/

Bug Tracker: https://shinmera.com/project/cl-ktx2/issues

Sources: https://shinmera.com/project/cl-ktx2.git

Definition Index

ORG.SHIRAKUMO.KTX2

No documentation provided.

EXTERNAL STRUCTURE

DESCRIPTOR-BLOCK

An opaque descriptor for the image data layout.

See DESCRIPTOR-BLOCK-VENDOR-ID
See DESCRIPTOR-BLOCK-TYPE
See DESCRIPTOR-BLOCK-VERSION
See DESCRIPTOR-BLOCK-SIZE
See DESCRIPTOR-BLOCK-DATA
See DATA-FORMAT-DESCRIPTORS

EXTERNAL STRUCTURE

FILE

Representation of a KTX2 file.

See VK-FORMAT
See TYPE-SIZE
See WIDTH
See HEIGHT
See DEPTH
See LAYER-COUNT
See FACE-COUNT
See LEVEL-COUNT
See SUPERCOMPRESSION-SCHEME
See LEVELS
See DFD-STORE
See KVD-STORE
See SUPERCOMPRESSION-GLOBAL-DATA
See LEVEL-IMAGES
See METADATA
See DATA-FORMAT-DESCRIPTORS
See GL-FLAGS
See GL-TEXTURE-TARGET
See GL-TYPE
See GL-INTERNAL-FORMAT
See GL-FORMAT
See READ-FILE
See WRITE-FILE
See TELL-FILE

EXTERNAL STRUCTURE

KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK

Describes the storage format of the image file.

See DESCRIPTOR-BLOCK (type)
See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-COLOR-MODEL
See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-COLOR-PRIMARIES
See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-TRANSFER-FUNCTION
See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-FLAGS
See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-TEXEL-BLOCK-DIMENSIONS
See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-BYTES-PLANES
See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-SAMPLES

EXTERNAL STRUCTURE

KV-ENTRY

Representation of a key/value pair.

See KV-ENTRY-KEY
See KV-ENTRY-VALUE
See METADATA
See KVD-STORE

EXTERNAL STRUCTURE

LEVEL

Representation of the information about a mipmap level.

See LEVEL-OFFSET
See LEVEL-LENGTH
See LEVEL-UNCOMPRESSED-LENGTH
See LEVEL-IMAGES

EXTERNAL STRUCTURE

SAMPLE-INFORMATION

Description of a sample in a Khronos basic data format descriptor.

See SAMPLE-INFORMATION-BIT-OFFSET
See SAMPLE-INFORMATION-BIT-LENGTH
See SAMPLE-INFORMATION-CHANNEL-TYPE
See SAMPLE-INFORMATION-POSITIONS
See SAMPLE-INFORMATION-LOWER
See SAMPLE-INFORMATION-UPPER

EXTERNAL FUNCTION

DATA-FORMAT-DESCRIPTORS

FILE

Returns the vector of DESCRIPTOR-BLOCK instances.

The descriptors are decoded to their specific type if it is known.
Otherwise an opaque DESCRIPTOR-BLOCK instance is used.

See FILE (type)

EXTERNAL FUNCTION

DEPTH

INSTANCE

Returns the number of pixels in depth (if 3D).

See FILE (type)

EXTERNAL FUNCTION
(SETF DEPTH)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

DESCRIPTOR-BLOCK-DATA

INSTANCE

Returns the octet vector holding the descriptor block's data payload.

See DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION
(SETF DESCRIPTOR-BLOCK-DATA)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

DESCRIPTOR-BLOCK-SIZE

INSTANCE

Returns the size of the descriptor block in octets.

See DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION
(SETF DESCRIPTOR-BLOCK-SIZE)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

DESCRIPTOR-BLOCK-TYPE

BLOCK

Returns the 15-bit type ID of the descriptor block.

See DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION

DESCRIPTOR-BLOCK-VENDOR-ID

BLOCK

Returns the 17-bit vendor ID of the descriptor block.

See DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION

DESCRIPTOR-BLOCK-VERSION

INSTANCE

Returns the 16-bit version of the descriptor block.

See DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION
(SETF DESCRIPTOR-BLOCK-VERSION)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

DFD-STORE

INSTANCE

Returns the raw data format descriptors octet vector.

See DATA-FORMAT-DESCRIPTORS
See FILE (type)

EXTERNAL FUNCTION
(SETF DFD-STORE)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

FACE-COUNT

INSTANCE

Returns the number of faces (if a cubemap).

See FILE (type)

EXTERNAL FUNCTION
(SETF FACE-COUNT)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

GL-FLAGS

FILE

Returns a plist of OpenGL flags describing the image properties.

The keys are:
  :TYPE
  :FORMAT
  :INTERNAL-FORMAT

This uses the KTXglFormat kv-pair if provided, or derives the values
from the vk-format if not.

See GL-TYPE
See GL-INTERNAL-FORMAT
See GL-FORMAT
See VK-FORMAT
See FILE (type)

EXTERNAL FUNCTION

GL-FORMAT

FILE

Returns the texture pixel format.

See GL-FLAGS
See FILE (type)

EXTERNAL FUNCTION

GL-INTERNAL-FORMAT

FILE

Returns the texture internal format.

See GL-FLAGS
See FILE (type)

EXTERNAL FUNCTION

GL-TEXTURE-TARGET

FILE

Returns the texture target for the image type.

Can be one of:
  :TEXTURE-3D
  :TEXTURE-CUBE-MAP
  :TEXTURE-2D
  :TEXTURE-1D
  :TEXTURE-3D-ARRAY
  :TEXTURE-CUBE-MAP-ARRAY
  :TEXTURE-2D-ARRAY
  :TEXTURE-1D-ARRAY

See FILE (type)

EXTERNAL FUNCTION

GL-TYPE

FILE

Returns the texture pixel type.

See GL-FLAGS
See FILE (type)

EXTERNAL FUNCTION

HEIGHT

INSTANCE

Returns the number of pixels in height (if 2D or 3D).

See FILE (type)

EXTERNAL FUNCTION
(SETF HEIGHT)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-BYTES-PLANES

INSTANCE

Vector describing the number of bytes the format uses per pixel plane/channel.

See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION
(SETF KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-BYTES-PLANES)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-COLOR-MODEL

INSTANCE

Returns the color model descriptor as a keyword symbol.

See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION
(SETF KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-COLOR-MODEL)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-COLOR-PRIMARIES

INSTANCE

Returns the description of the color primaries as a keyword symbol.

See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION
(SETF KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-COLOR-PRIMARIES)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-FLAGS

INSTANCE

Returns the colour flags as a bitmask.

The bits are as follows:
  0: premultiplied-alpha

See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION
(SETF KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-FLAGS)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-SAMPLES

INSTANCE

Returns a vector of SAMPLE-INFORMATION instances.

See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION
(SETF KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-SAMPLES)
- VALUE
- INSTANCE
Source
No documentation provided.
EXTERNAL FUNCTION
KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-SIZE
- INSTANCE
Source
No documentation provided.
EXTERNAL FUNCTION
(SETF KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-SIZE)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-TEXEL-BLOCK-DIMENSIONS

INSTANCE

Vector describing the range of coordinates covered by each texel block in that dimension.

See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION
(SETF KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-TEXEL-BLOCK-DIMENSIONS)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-TRANSFER-FUNCTION

INSTANCE

Returns the description of the color transfer function as a keyword symbol.

See KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK (type)

EXTERNAL FUNCTION
(SETF KHRONOS-BASIC-DATA-FORMAT-DESCRIPTOR-BLOCK-TRANSFER-FUNCTION)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

KV-ENTRY-KEY

KV-ENTRY

Returns the key of the entry as a string.

See KV-ENTRY (type)

EXTERNAL FUNCTION

KV-ENTRY-VALUE

KV-ENTRY

Accesses the value of the entry.

The value is decoded/encoded if the key is known.
If it is not known, the value is an octet-vector.

Known keys are:
  KTXcubemapIncomplete
  KTXorientation
  KTXglFormat
  KTXdxgiFormat__
  KTXmetalPixelFormat
  KTXswizzle
  KTXwriter
  KTXwriterScParams
  KTXanimData

See KV-ENTRY (type)
See DECODE-KV-ENTRY-VALUE
See ENCODE-KV-ENTRY-VALUE

EXTERNAL FUNCTION

KVD-STORE

INSTANCE

Returns the raw key-value store octet vector.

See METADATA
See FILE (type)

EXTERNAL FUNCTION
(SETF KVD-STORE)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

LAYER-COUNT

INSTANCE

Returns the number of image layers (if an array).

See FILE (type)

EXTERNAL FUNCTION
(SETF LAYER-COUNT)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

LEVEL-COUNT

INSTANCE

Returns the number of mipmap levels.

See FILE (type)

EXTERNAL FUNCTION
(SETF LEVEL-COUNT)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

LEVEL-IMAGES

INSTANCE

Returns the vector of octet-vectors that make up the mipmap level images.

See FILE (type)

EXTERNAL FUNCTION
(SETF LEVEL-IMAGES)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

LEVEL-LENGTH

INSTANCE

Returns the number of octets of the mipmap level.

This should typically not be necessary to access directly.

See LEVEL (type)

EXTERNAL FUNCTION
(SETF LEVEL-LENGTH)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

LEVEL-OFFSET

INSTANCE

Returns the number of octets since the start of the file at which the mipmap level starts.

This should typically not be necessary to access directly.

See LEVEL (type)

EXTERNAL FUNCTION
(SETF LEVEL-OFFSET)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

LEVEL-UNCOMPRESSED-LENGTH

INSTANCE

Returns the number of octets of the mipmap level when uncompressed.

See LEVEL (type)

EXTERNAL FUNCTION
(SETF LEVEL-UNCOMPRESSED-LENGTH)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

LEVELS

INSTANCE

Returns the vector of mipmap level descriptors.

See FILE (type)

EXTERNAL FUNCTION
(SETF LEVELS)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

METADATA

FILE

Returns a hash table with the key-value pairs.

The keys are keyword symbols naming the key item.

See KV-ENTRY-VALUE
See FILE (type)

EXTERNAL FUNCTION
(SETF METADATA)
- TABLE
- FILE
Source
No documentation provided.

EXTERNAL FUNCTION

READ-FILE

STORAGE
&REST
ARGS

Attempts to parse a KTX2 file from the given storage backend.

By default at the very least an octet-stream, a filename, or an
octet-vector and its size are supported as storage backends. Please
see the documentation of binary-structures for more information.

If successful returns a FILE instance.
If the file fails to parse (most likely because the file is malformed)
an error is signalled.

See FILE (type)
See TELL-FILE

EXTERNAL FUNCTION

SAMPLE-INFORMATION-BIT-LENGTH

INSTANCE

Returns the number of consecutive bits from the concatenated bit stream that contribute to the sample.

See SAMPLE-INFORMATION (type)

EXTERNAL FUNCTION
(SETF SAMPLE-INFORMATION-BIT-LENGTH)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

SAMPLE-INFORMATION-BIT-OFFSET

INSTANCE

Returns the offset of the least significant bit of this sample from the least significant bit of the least significant byte of the concatenated bit stream for the format.

See SAMPLE-INFORMATION (type)

EXTERNAL FUNCTION
(SETF SAMPLE-INFORMATION-BIT-OFFSET)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

SAMPLE-INFORMATION-CHANNEL-TYPE

INSTANCE

Returns a bitfield flag representing the following information:

The bits are as follows:
  0-3: 4-bit integer numbering the channel being described
  4: linear
  5: exponent
  6: signed
  7: float

See SAMPLE-INFORMATION (type)

EXTERNAL FUNCTION
(SETF SAMPLE-INFORMATION-CHANNEL-TYPE)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

SAMPLE-INFORMATION-LOWER

INSTANCE

Returns the lower sample reference value.

See SAMPLE-INFORMATION (type)

EXTERNAL FUNCTION
(SETF SAMPLE-INFORMATION-LOWER)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

SAMPLE-INFORMATION-POSITIONS

INSTANCE

Returns a vector describing the position of the sample within the texel block's 4D space.

See SAMPLE-INFORMATION (type)

EXTERNAL FUNCTION
(SETF SAMPLE-INFORMATION-POSITIONS)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

SAMPLE-INFORMATION-UPPER

INSTANCE

Returns the upper sample reference value.

See SAMPLE-INFORMATION (type)

EXTERNAL FUNCTION
(SETF SAMPLE-INFORMATION-UPPER)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

SUPERCOMPRESSION-GLOBAL-DATA

INSTANCE

Returns the raw supercompression global data octet vector.

See SUPERCOMPRESSION-SCHEME
See FILE (type)

EXTERNAL FUNCTION
(SETF SUPERCOMPRESSION-GLOBAL-DATA)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

SUPERCOMPRESSION-SCHEME

INSTANCE

Returns the supercompression scheme used, if any.

See FILE (type)

EXTERNAL FUNCTION
(SETF SUPERCOMPRESSION-SCHEME)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

TELL-FILE

STORAGE
&REST
ARGS

Attempts to parse a KTX2 file from the given storage backend.

Only the header of the file is parsed with the format, type-size,
width, height, depth, layer-count, face-count, level-count, and
supercompression-scheme fields. The returned FILE instance thus only
has those fields set to valid values.

Use this to as quickly as possible scan the file ahead of a full
loading sequence.

See FILE (type)
See READ-FILE

EXTERNAL FUNCTION

TYPE-SIZE

INSTANCE

Returns the number of octets per pixel.

See FILE (type)

EXTERNAL FUNCTION
(SETF TYPE-SIZE)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

VK-FORMAT

INSTANCE

Returns the vk_Format type representing the pixel encoding of the image data.

See FILE (type)
See GL-TYPE
See GL-INTERNAL-FORMAT
See GL-FORMAT

EXTERNAL FUNCTION
(SETF VK-FORMAT)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

WIDTH

INSTANCE

Returns the number of pixels in width.

See FILE (type)

EXTERNAL FUNCTION
(SETF WIDTH)
- VALUE
- INSTANCE
Source
No documentation provided.

EXTERNAL FUNCTION

WRITE-FILE

VALUE
STORAGE
&REST
ARGS

Writes the given KTX2 file to the given storage backend.

By default at the very least an octet-stream, a filename, or an
octet-vector and its size are supported as storage backends. Please
see the documentation of binary-structures for more information.

If the file fails to serialize (most likely because the file is
malformed) an error is signalled.

See FILE (type)

EXTERNAL GENERIC-FUNCTION

DECODE-KV-ENTRY-VALUE

KEY
OCTETS

Decodes the value from the octet vector based on its key.

The key must be given by a keyword symbol.

The user may add methods to this function to decode additional keys.

See KV-ENTRY-VALUE
See ENCODE-KV-ENTRY-VALUE

EXTERNAL GENERIC-FUNCTION

ENCODE-KV-ENTRY-VALUE

KEY
VALUE

Encodes the value to an octet vector based on its key.

The key must be given by a keyword symbol.

The user may add methods to this function to encode additional keys.

See KV-ENTRY-VALUE
See DECODE-KV-ENTRY-VALUE