bc5

README

go-bc5

A golang implementation of the BC5 red/green image compression technique.

GoDoc: https://godoc.org/github.com/leylandski/go-bc5

Compression/decompression CLI tool: https://github.com/leylandski/bc5-converter

Overview

This library can compress and decompress RGBA image data to and from BC5 encoded blocks. It also includes functionality for writing and reading BC5 encoded data to/from an io.Writer or io.Reader.

BC5 data encoded using *BC5.Encode(w io.Writer) will write a 12-byte header at the beginning of the stream, containing the uint32 equivalent of "BC5 " encoded in Big Endian format (0x42433520) followed by two uint32 values denoting the width and height of the image. The proceeding byte is the start of the block data and continues until EOF. In addition, *BC5.Decode(r io.Reader) expects the header and will error if it is not present.

The image on the left is the original, and the image on the right has been compressed and decompressed. The blue value difference is due to the original not being normalised.

About BC5

BC5 is a two-channel image compression format where the red and green components in a 4x4 block of pixels are mapped to interpolated colour values between two stored reference colours. Each pixel in the 4x4 grid is assigned a 3-bit index stored along with the reference colours to be interpolated at runtime. The full spec for the BC5 format can be found in the MSDN documentation here: https://docs.microsoft.com/en-gb/windows/win32/direct3d10/d3d10-graphics-programming-guide-resources-block-compression#bc5

The format is ideal for heightmaps or tangent-space normal maps where the blue component of each pixel can be reconstructed without much data loss.

For greyscale heightmaps, BC4 may produce smaller output files as only one channel is really needed. More sophisticated tools may gain the benefit of having an extra channel to work with when using over BC4 however, so it has its uses.

BC5 is ideally used for normal maps where only the x (red) and y (green) normal components need to be sampled by a shader, and the z (blue) is reconstructed with the assumption the original image was normalized.

Notice

This is an early attempt at implementing the raw BC5 compression/decompression algorithm. Once any header is removed, the data format should be acceptable to OpenGL using the COMPRESSED_RG_RGTC2 format. I have not tested this however, so use at your own risk and feel free to contact me if you find any inconsistencies with the specification.

TODO

• Test with OpenGL.
• Improve API for dealing with the header. Allow the programmer to specify their own for writing and a func interface for parsing them.
• Add a CompressFromData function to allow more flexibility.

Documentation

Overview

A package containing an implementation of the BC5 red/green image compression algorithm.

Index

• func Encode(img *BC5, w io.Writer) error
• type BC5
  • func Decode(r io.Reader) (*BC5, error)
  • func NewBC5FromFile(bcfile string) (*BC5, error)
  • func NewBC5FromRGBA(rgba *image.RGBA) (*BC5, error)
  • func (b BC5) At(x, y int) color.RGBA
  • func (b BC5) Decompress() *image.RGBA
  • func (b *BC5) SetFromRGBA(rgba *image.RGBA) error
  • func (b BC5) Size() int32
• type BlueMode

Functions

func Encode

func Encode(img *BC5, w io.Writer) error

Encode writes the contents of img to w, along with a 12 byte header containing the uint32 encoding of "BC5 ", followed by two more uint32 values for width and height, followed by all the block data.

Types

type BC5

type BC5 struct {
	Data []byte
	Rect image.Rectangle
	BlueMode
}

BC5 holds BC5-compressed red/green image data. The spec can be found here: https://docs.microsoft.com/en-us/windows/win32/direct3d10/d3d10-graphics-programming-guide-resources-block-compression#bc5

func Decode

func Decode(r io.Reader) (*BC5, error)

Decode reads BC5 encoded data from a reader into a new BC5 and returns a pointer to it. It expects a signature equal to "BC5 ", then two uint32 values for width and height, followed by all the block data. It will return an error if the data could not be decoded properly.

func NewBC5FromFile

func NewBC5FromFile(bcfile string) (*BC5, error)

Load reads BC5 encoded image data from imgfile into a BC5 and returns a pointer to it. It will return an error if one occurred.

func NewBC5FromRGBA

func NewBC5FromRGBA(rgba *image.RGBA) (*BC5, error)

NewBC5FromRGBA returns a BC5 containing the compressed form of an RGBA image.

func (BC5) At

func (b BC5) At(x, y int) color.RGBA

At performs on-the-fly decompression of b and returns the RGBA color at (x,y).

func (BC5) Decompress

func (b BC5) Decompress() *image.RGBA

Decompress returns an RGBA image containing the decompressed contents of b.

func (*BC5) SetFromRGBA

func (b *BC5) SetFromRGBA(rgba *image.RGBA) error

SetFromRGBA encodes RGBA data into this BC5 image. As this is a red/green compression scheme, the blue and alpha components of the source are discarded.

func (BC5) Size

func (b BC5) Size() int32

Size returns the number of bytes of pixel data b holds

type BlueMode

type BlueMode int

Alias for decompression blue computation constants.

const (
	Zero          BlueMode = iota //Always set the blue component to 0 during decompression.
	One                           //Always set the blue component to 1 during decompression.
	ComputeNormal                 //Compute the normal as (sqrt(1-((2*r-1)^2+(2*g-1)^2)))/2+0.5. Suitable for normalised maps.
	Greyscale                     //Computes the blue component to be identical to the red component per pixel.
)