The calino package provides a command-line interface for performing tasks such as
creating textures, validating textures, and extracting texture data to various file
formats. The base
calino command is broken into a number of subcommands which are documented
over the following sections.
All of the command-line functionality is implemented using the standard
calino APIs. Applications wishing to do
more advanced image processing should use those APIs directly.
check - Validate texture files
The check command validates texture files.
The
check command will read the texture file specified with
--file and perform extensive validity testing against the
properties given in the
calino
specification.
Additionally, it will extract all image data into memory and check the data against
any
CRC32 checksums included in the texture file.
If the command encounteres no validation errors or warnings, it will not print anything.
create-2d - Create 2D textures
The create-2d command creates 2D texture files.
The command takes an image file specified with --file and writes a texture
file to --output.
If the --mipmap-generate parameter is specified with a value of one of
the named filters [BICUBIC, BILINEAR, NEAREST] then a series of mipmaps will be
generated in the texture file with each scaled-down mip level being processed with
the given filter.
If the --byte-order parameter is specified with a value of one of the
named endianness values [BIG_ENDIAN, LITTLE_ENDIAN]. The endianness value
determines how image data will be stored and is primarily useful for applications
that wish to memory-map
texture files for direct uploading to GPUs.
The
--convert-layout-to parameter specifies that the image data provided by
the input file should be converted to the given
channel layout.
The
--metadata parameter specifies a file containing key/value metadata in
Java properties
format. The metadata keys and values will be inserted into the generated texture file.
If the --premultiply-alpha parameter is specified, then the data in the
input file will be alpha-premultiplied when written to the output texture file.
If the --super-compression parameter is specified, then the image data in
the output file will be compressed using the given compression method. Currently,
the only supported
supercompression method is LZ4.
create-array - Create array textures
The create-array command creates array texture files.
The command takes a series of image files specified with repeated instances of
--source-layer, and writes a texture file to
--output. The layers of the resulting array image will match the
order in which --source-layer parameters were specified, with
the first instance of --source-layer defining layer
0, and the nth instance of
--source-layer defining layer n-1.
If the --mipmap-generate parameter is specified with a value of one of
the named filters [BICUBIC, BILINEAR, NEAREST] then a series of mipmaps will be
generated in the texture file with each scaled-down mip level being processed with
the given filter.
If the --byte-order parameter is specified with a value of one of the
named endianness values [BIG_ENDIAN, LITTLE_ENDIAN]. The endianness value
determines how image data will be stored and is primarily useful for applications
that wish to memory-map
texture files for direct uploading to GPUs.
The
--convert-layout-to parameter specifies that the image data provided by
the input file should be converted to the given
channel layout.
The
--metadata parameter specifies a file containing key/value metadata in
Java properties
format. The metadata keys and values will be inserted into the generated texture file.
If the --premultiply-alpha parameter is specified, then the data in the
input file will be alpha-premultiplied when written to the output texture file.
If the --super-compression parameter is specified, then the image data in
the output file will be compressed using the given compression method. Currently,
the only supported
supercompression method is LZ4.
create-cube - Create cube textures
The create-cube command creates cube texture files.
The command takes a set of image files specified with
--source-x-negative,
--source-x-positive,
--source-y-negative,
--source-y-positive,
--source-z-negative,
and
--source-z-positive,
and writes a texture
file to --output.
If the --mipmap-generate parameter is specified with a value of one of
the named filters [BICUBIC, BILINEAR, NEAREST] then a series of mipmaps will be
generated in the texture file with each scaled-down mip level being processed with
the given filter.
If the --byte-order parameter is specified with a value of one of the
named endianness values [BIG_ENDIAN, LITTLE_ENDIAN]. The endianness value
determines how image data will be stored and is primarily useful for applications
that wish to memory-map
texture files for direct uploading to GPUs.
The
--convert-layout-to parameter specifies that the image data provided by
the input file should be converted to the given
channel layout.
The
--metadata parameter specifies a file containing key/value metadata in
Java properties
format. The metadata keys and values will be inserted into the generated texture file.
If the --premultiply-alpha parameter is specified, then the data in the
input file will be alpha-premultiplied when written to the output texture file.
If the --super-compression parameter is specified, then the image data in
the output file will be compressed using the given compression method. Currently,
the only supported
supercompression method is LZ4.
extract-image-data-2d - Extract image data from 2D textures.
The extract-image-data-2d command extracts image data from 2D texture files.
The command extracts all mipmaps available in the source texture to the output directory
specified
with
--output-directory. If source texture's mipmaps are compressed
with
supercompression
(such as
LZ4), then the mipmaps
can be optionally decompressed with
--decompress.
The output format can be specified with
--output-format which may be
one of
[RAW, PNG]. If the output format is
RAW, then the raw bytes that make up image data will be written to
the output files directly with no header or other information. If
--decompress
is
not specified, then the raw bytes will be those of the compressed data.
If the output format is
PNG, then the image data will be written to
the output files in
PNG
format. Note that this will necessarily and automatically decompress the image data,
and may also downsample
the image data because PNG does not support as wide a range of image data layouts
as
calino texture files.
For a given output directory D, the command will write each of
the mipmap levels of the input image to files in D. The name
of each output file will be "m", followed by a zero-padded
level number, followed by an appropriate file suffix such as
".png" or ".raw".
extract-image-data-array - Extract image data from array textures.
The extract-image-data-array command extracts image data from array texture files.
The command extracts all mipmaps available in the source texture to the output directory
specified
with
--output-directory. If source texture's mipmaps are compressed
with
supercompression
(such as
LZ4), then the mipmaps
can be optionally decompressed with
--decompress.
The output format can be specified with
--output-format which may be
one of
[RAW, PNG]. If the output format is
RAW, then the raw bytes that make up image data will be written to
the output files directly with no header or other information. If
--decompress
is
not specified, then the raw bytes will be those of the compressed data.
If the output format is
PNG, then the image data will be written to
the output files in
PNG
format. Note that this will necessarily and automatically decompress the image data,
and may also downsample
the image data because PNG does not support as wide a range of image data layouts
as
calino texture files.
For a given output directory D, the command will write each of
the mipmap levels of the input image to files in D. The name
of each output file will be "m", followed by a zero-padded
level number, followed by "v", followed by a zero-padded
layer number, followed by an appropriate file suffix such as
".png" or ".raw".
extract-image-data-cube - Extract image data from cube textures.
The extract-image-data-cube command extracts image data from cube texture files.
The command extracts all mipmaps available in the source texture to the output directory
specified
with
--output-directory. If source texture's mipmaps are compressed
with
supercompression
(such as
LZ4), then the mipmaps
can be optionally decompressed with
--decompress.
The output format can be specified with
--output-format which may be
one of
[RAW, PNG]. If the output format is
RAW, then the raw bytes that make up image data will be written to
the output files directly with no header or other information. If
--decompress
is
not specified, then the raw bytes will be those of the compressed data.
If the output format is
PNG, then the image data will be written to
the output files in
PNG
format. Note that this will necessarily and automatically decompress the image data,
and may also downsample
the image data because PNG does not support as wide a range of image data layouts
as
calino texture files.
For a given output directory D, the command will write each of
the mipmap levels of the input image to files in D. The name
of each output file will be "m", followed by a zero-padded
level number, followed by "f", followed by a face name,
followed by an appropriate file suffix such as
".png" or ".raw".
A face name is one of the following:
show-image-info - Show image information in texture files.
The show-image-info command displays the image information section in texture files.
The command displays the contents of the
image info
section directly, and does not validate that the texture file actually contains image
data of
the declared type.
show-metadata - Show metadata in texture files.
The show-metadata command displays metadata in texture files.
The command displays the contents of the
metadata section
in the texture file, if one exists.
show-sections - Show sections in texture files.
The show-sections command displays the sections present in texture files.
The command will print one line per section s in the given texture file.
If
s is of a type recognized by the implementation, then the line printed
for
s will be
i k (r) @o 'size' n,
where
i is the index of the section within the file (starting at
0),
k is the name of the section,
r is the raw 64-bit
section identifier,
o is the absolute base-16 offset of the start of the section within the file,
and
n is the base-16 size of the section.
If
s is of a type
not recognized by the implementation,
then the line printed
for
s will be
i r @o 'size' n,
where
i is the index of the section within the file (starting at
0),
r is the raw 64-bit
section identifier,
o is the absolute base-16 offset of the start of the section within the file,
and
n is the base-16 size of the section.
show-summary - Summarize texture files.
The show-summary command displays a summary of a texture file.
The command effectively summarizes the data given in the
image info
section, in addition to optionally listing all of the types, sizes, and offsets of
mipmaps
in the actual image data if requested with the
--show-mipmaps
parameter.
show-version - Show a texture file version.
The show-version command displays the format version used by a texture file.
version - Display the Calino tool version
The version command displays the current version of the command-line tool.
Documentation for the
calino APIs are provided in the
form of
JavaDoc.