Interface IGorgonImageUpdateFluent

Functionality for editing the image using a fluent interface.

Inherited Members
Namespace: Gorgon.Graphics.Imaging
Assembly: Gorgon.Graphics.Imaging.dll
Syntax
public interface IGorgonImageUpdateFluent : IGorgonImageUpdateFinalize

Methods

| Edit this page View Source

Compress(BufferFormat, bool, BcCompressionQuality, bool)

Function to compress the image data using block compression.

Declaration
IGorgonImageUpdateFinalize Compress(BufferFormat compressionFormat, bool useBC1Alpha = false, BcCompressionQuality quality = BcCompressionQuality.Fast, bool multithreadCompression = true)
Parameters
Type Name Description
BufferFormat compressionFormat

The block compression format to use. Must be one of the BCn formats.
bool useBC1Alpha

[Optional] true if using BC1 (DXT1) compression, and the image contains alpha, false if no alpha is in the image.
BcCompressionQuality quality

[Optional] The quality level for the compression.
bool multithreadCompression

[Optional] true to use multithreading while compressing the data, false to only use a single thread.
Returns
Type Description
IGorgonImageUpdateFinalize

The fluent interface to end the update.
Remarks

This method will compress the data within the image using the standardized block compression formats. The BufferFormat enum contains 7 levels of block compression named BC1 - BC7. The features of each compression level are documented at .

Block compression is, by nature, a lossy compression format. Thus some fidelity will be lost when compressing the data, it is recommended that images be compressed as a last stage in processing. Because block compression lays the image data out differently than standard image data, the functionality provided for modifying an image (e.g. Resize(int, int, int?, ImageFilter)) will not work and will throw an exception if used on block compressed data.

warning

Because block compressed data is lossy, it is not recommended that images be decompressed and compressed over and over as it will degrade the image fidelity severely. Thus, the recommendation to perform block compression only after all other processing is done.

The image data being compressed must be able to convert to a 32bit RGBA format, and must be uncompressed. If it cannot, then an exception will be thrown.

important

The BC6H_Sf16, and BC6H_Uf16 block compression types are not implemented at this time. If it is used, then an exception will be thrown. This may change in the future.

Typeless formats are not supported at all, and will not be.

The higher levels of block compression provide much better image quality, however they perform much slower. Especially when single threaded, it is recommended that the multithreadCompression value be set to true when using BC7 compression.

When using BC1 compression, optional 1-bit alpha channel data can be stored with the image data. The developer must specify whether to use the alpha data or not via the useBC1Alpha parameter.

Unlike the Decompress(bool) method, this method does not return an image. This is done to signify that the compress operation is the last operation in a chain of calls via the image modification fluent interface.

See Also
| Edit this page View Source

ConvertFromPremultipedAlpha()

Function to convert the image data from a premultiplied format.

Declaration
IGorgonImageUpdateFluent ConvertFromPremultipedAlpha()
Returns
Type Description
IGorgonImageUpdateFluent

A IGorgonImage containing the image data with the premultiplied alpha removed from the pixel data.
Remarks

Use this to convert an image from a premultiplied format. This takes each Red, Green and Blue element and divides them by the Alpha element.

If the image does not contain alpha then the method will return right away and no alterations to the image will be performed.

| Edit this page View Source

ConvertToFormat(BufferFormat, ImageDithering)

Function to convert the pixel format of an image into another pixel format.

Declaration
IGorgonImageUpdateFluent ConvertToFormat(BufferFormat format, ImageDithering dithering = ImageDithering.None)
Parameters
Type Name Description
BufferFormat format

The new pixel format for the image.
ImageDithering dithering

[Optional] Flag to indicate the type of dithering to perform when the bit depth for the format is lower than the original bit depth.
Returns
Type Description
IGorgonImageUpdateFluent

A IGorgonImage containing the image data with the converted pixel format.
Remarks

Use this to convert an image format from one to another. The conversion functionality uses Windows Imaging Components (WIC) to perform the conversion.

Because this method uses WIC, not all formats will be convertible. To determine if a format can be converted, use the CanConvertToFormat(BufferFormat) method.

For the B4G4R4A4_UNorm format, Gorgon has to perform a manual conversion since that format is not supported by WIC. Because of this, the dithering flag will be ignored when downsampling to that format.

| Edit this page View Source

ConvertToPremultipliedAlpha()

Function to convert the image data into a premultiplied format.

Declaration
IGorgonImageUpdateFluent ConvertToPremultipliedAlpha()
Returns
Type Description
IGorgonImageUpdateFluent

A IGorgonImage containing the image data with the premultiplied alpha pixel data.
Remarks

Use this to convert an image to a premultiplied format. This takes each Red, Green and Blue element and multiplies them by the Alpha element.

If the image does not contain alpha then the method will return right away and no alterations to the image will be performed.

| Edit this page View Source

Crop(Rectangle, int?)

Function to crop the image to the rectangle passed to the parameters.

Declaration
IGorgonImageUpdateFluent Crop(Rectangle cropRect, int? newDepth = null)
Parameters
Type Name Description
Rectangle cropRect

The rectangle that will be used to crop the image.
int? newDepth

[Optional] The new depth for the image (for Image3D images).
Returns
Type Description
IGorgonImageUpdateFluent

A IGorgonImage containing the resized image.
Remarks

This method will crop the existing image a smaller version of itself as a new IGorgonImage. If the sizes are the same, or the cropRect is larger than the size of the original image, then no changes will be made.

| Edit this page View Source

Expand(int, int, int?, ImageExpandAnchor)

Function to expand an image width, height, and/or depth.

Declaration
IGorgonImageUpdateFluent Expand(int newWidth, int newHeight, int? newDepth = null, ImageExpandAnchor anchor = ImageExpandAnchor.UpperLeft)
Parameters
Type Name Description
int newWidth

The new width of the image.
int newHeight

The new height of the image.
int? newDepth

[Optional] The new depth of the image.
ImageExpandAnchor anchor

[Optional] The anchor point for placing the image data after the image is expanded.
Returns
Type Description
IGorgonImageUpdateFluent

The expanded image.
Remarks

This will expand the size of an image, but not stretch the actual image data. This will leave a padding around the original image area filled with transparent pixels.

The image data can be repositioned in the new image by specifying an anchor point.

If the new size of the image is smaller than that of this image, then the new size is constrained to the old size. Cropping is not supported by this method.

If a user wishes to resize the image, then call the Resize(int, int, int?, ImageFilter) method, of if they wish to crop an image, use the Crop(Rectangle, int?) method.

| Edit this page View Source

GenerateMipMaps(int, ImageFilter)

Function to generate a new mip map chain.

Declaration
IGorgonImageUpdateFluent GenerateMipMaps(int mipCount, ImageFilter filter = ImageFilter.Point)
Parameters
Type Name Description
int mipCount

The number of mip map levels.
ImageFilter filter

[Optional] The filter to apply when copying the data from one mip level to another.
Returns
Type Description
IGorgonImageUpdateFluent

A IGorgonImage containing the updated mip map data.
Remarks

This method will generate a new mip map chain for the mipCount. If the current number of mip maps is not the same as the requested number, then the image buffer will be adjusted to use the requested number of mip maps. If 0 is passed to mipCount, then a full mip map chain is generated.

Note that the mipCount may not be honored depending on the current width, height, and depth of the image. Check the width, height and/or depth property on the returned IGorgonImage to determine how many mip levels were actually generated.

| Edit this page View Source

Resize(int, int, int?, ImageFilter)

Function to resize the image to a new width, height and/or depth.

Declaration
IGorgonImageUpdateFluent Resize(int newWidth, int newHeight, int? newDepth = null, ImageFilter filter = ImageFilter.Point)
Parameters
Type Name Description
int newWidth

The new width for the image.
int newHeight

The new height for the image (for Image2D and ImageCube images).
int? newDepth

[Optional] The new depth for the image (for Image3D images).
ImageFilter filter

[Optional] The type of filtering to apply to the scaled image to help smooth larger and smaller images.
Returns
Type Description
IGorgonImageUpdateFluent

A IGorgonImage containing the resized image.
Remarks

This method will change the size of an existing image and return a larger or smaller version of itself as a new IGorgonImage.

Extension Methods