squish

package module
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 7, 2018 License: BSD-2-Clause Imports: 4 Imported by: 2

README

go-squish

GoDoc

About

libsquish is a small, portable C++ library for compressing and decompressing images with the DXT standard (also known as S3TC or BC). This standard is mainly used by OpenGL and DirectX for the lossy compression of RGBA textures..

This project provides Go bindings for libsquish. go-squish also provides a patch file that adds a C compatibility wrapper to libsquish, since Go doesn't support C++ libraries directly. Apply it before compiling the library. It is compatible with libsquish version 1.15.

Building

go-squish uses the system version of the static libisquish library. More information about how to build libimagequant can be found in the libisquish readme.

go-squish package path is currently github.com/InfinityTools/squish. The bindings can be built via go build.

This package makes use of CGO, which requires a decent C compiler to be installed. However, using go install removes the C compiler requirement for future invocations of go build.

Documentation

For docs, see https://godoc.org/github.com/InfinityTools/go-squish .

License

Both go-squish and the libsquish C wrapper patch are released under the BSD 2-clause license. See LICENSE for more details.

libsquish itself is available under under the MIT license. See libsquish-license.txt for more details.

Documentation

Overview

Package squish provides bindings to the external libsquish library to be used for compression and decompression of DXT-encoded pixel data.

Important: The original libSquish library is written in C++ and therefore not directly compatible with the CGo compiler tool. The included patch file "libsquish-1.15-c_wrapper.patch" adds a simple C wrapper. Apply it before building the C++ library.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Compression type
	FLAGS_DXT1 = int(C.ckDxt1)
	FLAGS_DXT3 = int(C.ckDxt3)
	FLAGS_DXT5 = int(C.ckDxt5)
	FLAGS_BC4  = int(C.ckBc4)
	FLAGS_BC5  = int(C.ckBc5)

	// Compression method. Quality ranges from "range fit" (lowest) to "iterative cluster fit" (highest).
	FLAGS_RANGE_FIT             = int(C.ckColourRangeFit)
	FLAGS_CLUSTER_FIT           = int(C.ckColourClusterFit)
	FLAGS_ITERATIVE_CLUSTER_FIT = int(C.ckColourIterativeClusterFit)

	// Additional flags
	FLAGS_WEIGHT_BY_ALPHA = int(C.ckWeightColourByAlpha)
	FLAGS_SOURCE_BGRA     = int(C.ckSourceBGRA)

	// The default metric. Applies the same weight to all color components on compression.
	METRIC_UNIFORM = []float32{1.0, 1.0, 1.0}
	// A popular metric that improves percepted quality.
	METRIC_PERCEPTUAL = []float32{0.2126, 0.7152, 0.0722}
)

Functions

func Compress 

func Compress(rgba []byte, block []byte, flags int, metric []float32) []byte

Compress compresses a 4x4 block of pixels. 

param rgba     The rgba values of the 16 source pixels.
param block    Storage for the compressed DXT block. Specify nil to auto-create.
param flags    Compression flags.
param metric   An optional perceptual metric.
return         The (updated) storage for the compressed DXT block.

The source pixels should be presented as a contiguous array of 16 rgba values, with each component as 1 byte each. In memory this should be: { r1, g1, b1, a1, .... , r16, g16, b16, a16 }

The flags parameter should specify FLAGS_DXT1, FLAGS_DXT3, FLAGS_DXT5, FLAGS_BC4, or FLAGS_BC5 compression, however, DXT1 will be used by default if none is specified. When using DXT1 compression, 8 bytes of storage are required for the compressed DXT block. DXT3 and DXT5 compression require 16 bytes of storage per block.

The flags parameter can also specify a preferred colour compressor to use when fitting the RGB components of the data. Possible colour compressors are: FLAGS_CLUSTER_FIT (the default), FLAGS_RANGE_FIT (very fast, low quality) or FLAGS_ITERATIVE_CLUSTER_FIT (slowest, best quality).

When using FLAGS_CLUSTER_FIT or FLAGS_ITERATIVE_CLUSTER_FIT, an additional flag can be specified to weight the importance of each pixel by its alpha value. For images that are rendered using alpha blending, this can significantly increase the perceived quality.

The metric parameter can be used to weight the relative importance of each colour channel, or pass NULL to use the default uniform weight of { 1.0f, 1.0f, 1.0f }. This replaces the previous flag-based control that allowed either uniform or "perceptual" weights with the fixed values { 0.2126f, 0.7152f, 0.0722f }. If non-NULL, the metric should point to a contiguous array of 3 floats.

This method is an inline that calls CompressMasked with a mask of 0xffff, provided for compatibility with older versions of squish.

func CompressBuffer 

func CompressBuffer(rgba []byte, width, height int, blocks []byte, flags int, metric []float32) []byte

CompressBuffer compresses an image in memory. It is identical to CompressBufferEx, except for the "pitch" parameter which is calculated from "width".

func CompressBufferEx 

func CompressBufferEx(rgba []byte, width, height, pitch int, blocks []byte, flags int, metric []float32) []byte

CompressBufferEx compresses an rgba pixel buffer in memory. 

param rgba     The pixels of the source.
param width    The width of the source image.
param height   The height of the source image.
param pitch    The pitch of the source image (CompressImage2 only).
param blocks   Storage for the compressed output. Specify nil to auto-create.
param flags    Compression flags.
param metric   An optional perceptual metric.
return         The (updated) storage for the compressed output.

The source pixels should be presented as a contiguous array of width*height rgba values, with each component as 1 byte each. In memory this should be: { r1, g1, b1, a1, .... , rn, gn, bn, an } for n = width*height

The flags parameter should specify FLAGS_DXT1, FLAGS_DXT3, FLAGS_DXT5, FLAGS_BC4, or FLAGS_BC5 compression, however, DXT1 will be used by default if none is specified. When using DXT1 compression, 8 bytes of storage are required for each compressed DXT block. DXT3 and DXT5 compression require 16 bytes of storage per block.

The flags parameter can also specify a preferred colour compressor to use when fitting the RGB components of the data. Possible colour compressors are: FLAGS_CLUSTER_FIT (the default), FLAGS_RANGE_FIT (very fast, low quality) or FLAGS_ITERATIVE_CLUSTER_FIT (slowest, best quality).

When using FLAGS_CLUSTER_FIT or FLAGS_ITERATIVE_CLUSTER_FIT, an additional flag can be specified to weight the importance of each pixel by its alpha value. For images that are rendered using alpha blending, this can significantly increase the perceived quality.

The metric parameter can be used to weight the relative importance of each colour channel, or pass NULL to use the default uniform weight of { 1.0f, 1.0f, 1.0f }. This replaces the previous flag-based control that allowed either uniform or "perceptual" weights with the fixed values { 0.2126f, 0.7152f, 0.0722f }. If non-NULL, the metric should point to a contiguous array of 3 floats.

Internally this function calls CompressMasked() for each block, which allows for pixels outside the image to take arbitrary values. The function GetStorageRequirements() can be called to compute the amount of memory to allocate for the compressed output.

Note on compression quality: When compressing textures with libsquish it is recommended to apply a gamma-correction beforehand. This will reduce the blockiness in dark areas. The level of necessary gamma-correction is platform dependent. For example, a gamma correction with gamma = 0.5 before compression and gamma = 2.0 after decompression yields good results on the Windows platform but for other platforms like MacOS X a different gamma value may be more suitable.

func CompressImage 

func CompressImage(img image.Image, flags int, metric []float32) []byte

CompressImage compresses an image in memory. 

param img      The source image.
param flags    Compression flags.
param metric   An optional perceptual metric.
return         Storage with the compressed output data.

func CompressMasked 

func CompressMasked(rgba []byte, mask int, block []byte, flags int, metric []float32) []byte

CompressMasked compresses a 4x4 block of pixels. 

param rgba     The rgba values of the 16 source pixels.
param mask     The valid pixel mask.
param block    Storage for the compressed DXT block. Specify nil to auto-create.
param flags    Compression flags.
param metric   An optional perceptual metric.
return         The (updated) storage for the compressed DXT block.

The source pixels should be presented as a contiguous array of 16 rgba values, with each component as 1 byte each. In memory this should be: { r1, g1, b1, a1, .... , r16, g16, b16, a16 }

The mask parameter enables only certain pixels within the block. The lowest bit enables the first pixel and so on up to the 16th bit. Bits beyond the 16th bit are ignored. Pixels that are not enabled are allowed to take arbitrary colours in the output block. An example of how this can be used is in the CompressImage function to disable pixels outside the bounds of the image when the width or height is not divisible by 4.

The flags parameter should specify FLAGS_DXT1, FLAGS_DXT3, FLAGS_DXT5, FLAGS_BC4, or FLAGS_BC5 compression, however, DXT1 will be used by default if none is specified. When using DXT1 compression, 8 bytes of storage are required for the compressed DXT block. DXT3 and DXT5 compression require 16 bytes of storage per block.

The flags parameter can also specify a preferred colour compressor to use when fitting the RGB components of the data. Possible colour compressors are: FLAGS_CLUSTER_FIT (the default), FLAGS_RANGE_FIT (very fast, low quality) or FLAGS_ITERATIVE_CLUSTER_FIT (slowest, best quality).

When using FLAGS_CLUSTER_FIT or FLAGS_ITERATIVE_CLUSTER_FIT, an additional flag can be specified to weight the importance of each pixel by its alpha value. For images that are rendered using alpha blending, this can significantly increase the perceived quality.

The metric parameter can be used to weight the relative importance of each colour channel, or pass NULL to use the default uniform weight of { 1.0f, 1.0f, 1.0f }. This replaces the previous flag-based control that allowed either uniform or "perceptual" weights with the fixed values { 0.2126f, 0.7152f, 0.0722f }. If non-NULL, the metric should point to a contiguous array of 3 floats.

func ComputeMSE 

func ComputeMSE(rgba []byte, width, height int, dxt []byte, flags int) (colorMSE, alphaMSE float64)

ComputeMSE computes MSE of an compressed image in memory. It is identical to ComputeMSEEx, except for the "pitch" parameter, which is calculated from "width".

func ComputeMSEEx 

func ComputeMSEEx(rgba []byte, width, height, pitch int, dxt []byte, flags int) (colorMSE, alphaMSE float64)

ComputeMSEEx computes MSE of an compressed image in memory. 

param rgba         The original image pixels.
param width        The width of the source image.
param height       The height of the source image.
param pitch        The pitch of the source image.
param dxt          The compressed dxt blocks
param flags        Compression flags.
return colourMSE   The MSE of the colour values.
return alphaMSE    The MSE of the alpha values.

The colour MSE and alpha MSE are computed across all pixels. The colour MSE is averaged across all rgb values (i.e. colourMSE = sum sum_k ||dxt.k - rgba.k||/3)

The flags parameter should specify FLAGS_DXT1, FLAGS_DXT3, FLAGS_DXT5, FLAGS_BC4, or FLAGS_BC5 compression, however, DXT1 will be used by default if none is specified. All other flags are ignored.

Internally this function calls Decompress() for each block.

func Decompress 

func Decompress(rgba []byte, block []byte, flags int) []byte

Decompress decompresses a 4x4 block of pixels. 

param rgba     Storage for the 16 decompressed pixels. Specify nil to auto-create.
param block    The compressed DXT block.
param flags    Compression flags.
return         The (update) storage for the 16 decompressed pixels.

The decompressed pixels will be written as a contiguous array of 16 rgba values, with each component as 1 byte each. In memory this is: { r1, g1, b1, a1, .... , r16, g16, b16, a16 }

The flags parameter should specify FLAGS_DXT1, FLAGS_DXT3, FLAGS_DXT5, FLAGS_BC4, or FLAGS_BC5 compression, however, DXT1 will be used by default if none is specified. All other flags are ignored.

func DecompressBuffer 

func DecompressBuffer(rgba []byte, width, height int, blocks []byte, flags int) []byte

DecompressBuffer decompresses an image in memory. It is identical to DecompressBufferEx, except for the "pitch" parameter which is calculated from "width".

func DecompressBufferEx 

func DecompressBufferEx(rgba []byte, width, height, pitch int, blocks []byte, flags int) []byte

DecompressBufferEx decompresses an image in memory. 

param rgba     Storage for the decompressed pixels. Specify nil to auto-create.
param width    The width of the source image.
param height   The height of the source image.
param pitch    The pitch of the decompressed pixels.
param blocks   The compressed DXT blocks.
param flags    Compression flags.
return         The (updated) storage for the decompressed pixels.

The decompressed pixels will be written as a contiguous array of width*height 16 rgba values, with each component as 1 byte each. In memory this is: { r1, g1, b1, a1, .... , rn, gn, bn, an } for n = width*height

The flags parameter should specify FLAGS_DXT1, FLAGS_DXT3, FLAGS_DXT5, FLAGS_BC4, or FLAGS_BC5 compression, however, DXT1 will be used by default if none is specified. All other flags are ignored.

Internally this function calls Decompress() for each block.

func DecompressImage 

func DecompressImage(width, height int, blocks []byte, flags int) image.Image

DecompressImage decompresses an image in memory. 

param width    The width of the source image.
param height   The height of the source image.
param blocks   The compressed DXT blocks as byte array.
param flags    Compression flags.
return         Image object containing the decompressed pixels. Returns nil on error.

func GetStorageRequirements 

func GetStorageRequirements(width, height, flags int) int

GetStorageRequirements computes the amount of compressed storage required. 

param width    The width of the image.
param height   The height of the image.
param flags    Compression flags.
return         The required amount of compressed storage in bytes.

The flags parameter should specify FLAGS_DXT1, FLAGS_DXT3, FLAGS_DXT5, FLAGS_BC4, or FLAGS_BC5 compression, however, DXT1 will be used by default if none is specified. All other flags are ignored.

Most DXT images will be a multiple of 4 in each dimension, but this function supports arbitrary size images by allowing the outer blocks to be only partially used.

func ImageToBytes 

func ImageToBytes(img image.Image) []byte

ImageToBytes converts the image pixel data into a sequence of bytes where pixels are laid out as { r1, g1, b1, a1, ..., rn, gn, bn, an }.

func NRGBA 

func NRGBA(col color.Color) (r, g, b, a byte)

NRGBA converts a premultiplied color back to a normalized color with each component in range [0, 255].

Types

This section is empty.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.