Image
Image datatype.
Image datatype.
Native image datatype. Contains image data which can be converted to an ImageTexture and provides commonly used image processing methods. The maximum width and height for an Image are Image.MaxWidth and Image.MaxHeight.
An Image cannot be assigned to a texture property of an object directly (such as Sprite2D.Texture), and has to be converted manually to an ImageTexture first.
Note: Methods that modify the image data cannot be used on VRAM-compressed images. Use Image.Decompress to convert the image to an uncompressed format first.
Note: The maximum image size is 16384×16384 pixels due to graphics hardware limitations. Larger images may fail to import.
Declarations checked against C# SDK 1.0.0. Expand a name to see declarations and documentation.
Constructors1
ImageConstructor
public Image();Properties1
DataProperty
public Reckfell.Collections.Dictionary Data { get; set; }Holds all the image's color data in a given format. See Image.Format constants.
Methods92
AdjustBcsvoid
public void AdjustBcs(float brightness, float contrast, float saturation);Adjusts this image's brightness, contrast, and saturation by the given values. Does not work if the image is compressed (see Image.IsCompressed).
| Name | Type | Default |
|---|---|---|
brightness | float | — |
contrast | float | — |
saturation | float | — |
BlendRectvoid
public void BlendRect(Image src, Rect2I srcRect, Vector2I dst);Alpha-blends src_rect from src image to this image at coordinates dst, clipped accordingly to both image bounds. This image and src image must have the same format. src_rect with non-positive size is treated as empty.
Note: Simultaneously reading and writing to the same image reference may lead to unexpected results.
| Name | Type | Default |
|---|---|---|
src | Image | — |
srcRect | Rect2I | — |
dst | Vector2I | — |
BlendRectMaskvoid
public void BlendRectMask(Image src, Image mask, Rect2I srcRect, Vector2I dst);Alpha-blends src_rect from src image to this image using mask image at coordinates dst, clipped accordingly to both image bounds. Alpha channels are required for both src and mask. dst pixels and src pixels will blend if the corresponding mask pixel's alpha value is not 0. This image and src image must have the same format. src image and mask image must have the same size (width and height) but they can have different formats. src_rect with non-positive size is treated as empty.
| Name | Type | Default |
|---|---|---|
src | Image | — |
mask | Image | — |
srcRect | Rect2I | — |
dst | Vector2I | — |
BlitRectvoid
public void BlitRect(Image src, Rect2I srcRect, Vector2I dst);Copies src_rect from src image to this image at coordinates dst, clipped accordingly to both image bounds. This image and src image must have the same format. src_rect with non-positive size is treated as empty.
Note: The alpha channel data in src will overwrite the corresponding data in this image at the target position. To blend alpha channels, use Image.BlendRect instead.
| Name | Type | Default |
|---|---|---|
src | Image | — |
srcRect | Rect2I | — |
dst | Vector2I | — |
BlitRectMaskvoid
public void BlitRectMask(Image src, Image mask, Rect2I srcRect, Vector2I dst);Blits src_rect area from src image to this image at the coordinates given by dst, clipped accordingly to both image bounds. src pixel is copied onto dst if the corresponding mask pixel's alpha value is not 0. This image and src image must have the same format. src image and mask image must have the same size (width and height) but they can have different formats. src_rect with non-positive size is treated as empty.
| Name | Type | Default |
|---|---|---|
src | Image | — |
mask | Image | — |
srcRect | Rect2I | — |
dst | Vector2I | — |
BumpMapToNormalMapvoid
public void BumpMapToNormalMap(float bumpScale = 1f);Converts a bump map to a normal map. A bump map provides a height offset per-pixel, while a normal map provides a normal direction per pixel.
| Name | Type | Default |
|---|---|---|
bumpScale | float | 1f |
ClearMipmapsvoid
public void ClearMipmaps();Removes the image's mipmaps.
Compress2 overloads
public Error Compress(Image.CompressMode mode, Image.CompressSource source, Image.AstcFormat astcFormat);Compresses the image with a VRAM-compressed format to use less memory. Can not directly access pixel data while the image is compressed. Returns error if the chosen compression mode is not available.
The source parameter helps to pick the best compression method for DXT and ETC2 formats. It is ignored for ASTC compression.
The profile lets the user pick whether the compression should prioritize quality or a smaller size. Only ASTC compression uses this currently.
Note: Image.Compress is only supported in editor builds. When run in an exported project, this method always returns ERR_UNAVAILABLE.
| Name | Type | Default |
|---|---|---|
mode | Image.CompressMode | — |
source | Image.CompressSource | — |
astcFormat | Image.AstcFormat | — |
Errorpublic Error Compress(Image.CompressMode mode, Image.CompressSource source = Image.CompressSource.Generic, Image.CompressProfile profile = Image.CompressProfile.Automatic);Compresses the image with a VRAM-compressed format to use less memory. Can not directly access pixel data while the image is compressed. Returns error if the chosen compression mode is not available.
The source parameter helps to pick the best compression method for DXT and ETC2 formats. It is ignored for ASTC compression.
The profile lets the user pick whether the compression should prioritize quality or a smaller size. Only ASTC compression uses this currently.
Note: Image.Compress is only supported in editor builds. When run in an exported project, this method always returns ERR_UNAVAILABLE.
| Name | Type | Default |
|---|---|---|
mode | Image.CompressMode | — |
source | Image.CompressSource | Image.CompressSource.Generic |
profile | Image.CompressProfile | Image.CompressProfile.Automatic |
ErrorCompressFromChannels2 overloads
public Error CompressFromChannels(Image.CompressMode mode, Image.UsedChannels channels, Image.AstcFormat astcFormat);Compresses the image with a VRAM-compressed format to use less memory. Can not directly access pixel data while the image is compressed. Returns error if the chosen compression mode is not available.
This is an alternative to Image.Compress that lets the user supply the channels used in order for the compressor to pick the best DXT, ETC2, and ASTC formats. For other formats (non DXT, ETC2, or ASTC), this argument is ignored.
The profile lets the user pick whether the compression should prioritize quality or a smaller size. Only ASTC compression uses this currently.
Note: Image.CompressFromChannels is only supported in editor builds. When run in an exported project, this method always returns ERR_UNAVAILABLE.
| Name | Type | Default |
|---|---|---|
mode | Image.CompressMode | — |
channels | Image.UsedChannels | — |
astcFormat | Image.AstcFormat | — |
Errorpublic Error CompressFromChannels(Image.CompressMode mode, Image.UsedChannels channels, Image.CompressProfile profile = Image.CompressProfile.Automatic);Compresses the image with a VRAM-compressed format to use less memory. Can not directly access pixel data while the image is compressed. Returns error if the chosen compression mode is not available.
This is an alternative to Image.Compress that lets the user supply the channels used in order for the compressor to pick the best DXT, ETC2, and ASTC formats. For other formats (non DXT, ETC2, or ASTC), this argument is ignored.
The profile lets the user pick whether the compression should prioritize quality or a smaller size. Only ASTC compression uses this currently.
Note: Image.CompressFromChannels is only supported in editor builds. When run in an exported project, this method always returns ERR_UNAVAILABLE.
| Name | Type | Default |
|---|---|---|
mode | Image.CompressMode | — |
channels | Image.UsedChannels | — |
profile | Image.CompressProfile | Image.CompressProfile.Automatic |
ErrorComputeImageMetricsReckfell.Collections.Dictionary
public Reckfell.Collections.Dictionary ComputeImageMetrics(Image comparedImage, bool useLuma);Compute image metrics on the current image and the compared image. This can be used to calculate the similarity between two images.
The dictionary contains max, mean, mean_squared, root_mean_squared and peak_snr.
| Name | Type | Default |
|---|---|---|
comparedImage | Image | — |
useLuma | bool | — |
Reckfell.Collections.DictionaryConvertvoid
public void Convert(Image.Format format);Converts this image's format to the given format.
| Name | Type | Default |
|---|---|---|
format | Image.Format | — |
CopyFromvoid
public void CopyFrom(Image src);Copies src image to this image.
| Name | Type | Default |
|---|---|---|
src | Image | — |
CreateImage · Deprecated
public static Image Create(int width, int height, bool useMipmaps, Image.Format format);Creates an empty image of the given size and format. If use_mipmaps is true, generates mipmaps for this image (see Image.GenerateMipmaps).
| Name | Type | Default |
|---|---|---|
width | int | — |
height | int | — |
useMipmaps | bool | — |
format | Image.Format | — |
ImageCreateEmptyImage
public static Image CreateEmpty(int width, int height, bool useMipmaps, Image.Format format);Creates an empty image of the given size and format. If use_mipmaps is true, generates mipmaps for this image (see Image.GenerateMipmaps).
| Name | Type | Default |
|---|---|---|
width | int | — |
height | int | — |
useMipmaps | bool | — |
format | Image.Format | — |
ImageCreateFromData2 overloads
public static Image CreateFromData(int width, int height, bool useMipmaps, Image.Format format, byte[] data);Creates a new image of the given size and format. Fills the image with the given raw data. If use_mipmaps is true, loads the mipmaps for this image from Image.Data. See Image.GenerateMipmaps.
| Name | Type | Default |
|---|---|---|
width | int | — |
height | int | — |
useMipmaps | bool | — |
format | Image.Format | — |
data | byte[] | — |
Imagepublic static Image CreateFromData(int width, int height, bool useMipmaps, Image.Format format, ReadOnlySpan<byte> data);Creates a new image of the given size and format. Fills the image with the given raw data. If use_mipmaps is true, loads the mipmaps for this image from Image.Data. See Image.GenerateMipmaps.
| Name | Type | Default |
|---|---|---|
width | int | — |
height | int | — |
useMipmaps | bool | — |
format | Image.Format | — |
data | ReadOnlySpan<byte> | — |
ImageCropvoid
public void Crop(int width, int height);Crops the image to the given width and height. If the specified size is larger than the current size, the extra area is filled with black pixels.
| Name | Type | Default |
|---|---|---|
width | int | — |
height | int | — |
DecompressError
public Error Decompress();Decompresses the image if it is VRAM-compressed in a supported format. This increases memory utilization, but allows modifying the image. Returns OK if the format is supported, otherwise ERR_UNAVAILABLE. All VRAM-compressed formats supported by Reckfell can be decompressed with this method, except Image.Format.Etc2R11S, Image.Format.Etc2Rg11S, and Image.Format.Etc2Rgb8A1.
ErrorDetectAlphaImage.AlphaMode
public Image.AlphaMode DetectAlpha();Returns Image.AlphaMode.Blend if the image has data for alpha values. Returns Image.AlphaMode.Bit if all the alpha values are stored in a single bit. Returns Image.AlphaMode.None if no data for alpha values is found.
Image.AlphaModeDetectUsedChannelsImage.UsedChannels
public Image.UsedChannels DetectUsedChannels(Image.CompressSource source = Image.CompressSource.Generic);Returns the color channels used by this image. If the image is compressed, the original source must be specified.
| Name | Type | Default |
|---|---|---|
source | Image.CompressSource | Image.CompressSource.Generic |
Image.UsedChannelsFillvoid
public void Fill(Color color);Fills the image with color.
| Name | Type | Default |
|---|---|---|
color | Color | — |
FillRectvoid
public void FillRect(Rect2I rect, Color color);Fills rect with color.
| Name | Type | Default |
|---|---|---|
rect | Rect2I | — |
color | Color | — |
FixAlphaEdgesvoid
public void FixAlphaEdges();Blends low-alpha pixels with nearby pixels.
FlipXvoid
public void FlipX();Flips the image horizontally.
FlipYvoid
public void FlipY();Flips the image vertically.
GenerateMipmaps2 overloads
public Error GenerateMipmaps(bool renormalize);Generates mipmaps for the image. Mipmaps are precalculated lower-resolution copies of the image that are automatically used if the image needs to be scaled down when rendered. They help improve image quality and performance when rendering. This method returns an error if the image is compressed, in a custom format, or if the image's width/height is 0. Enabling renormalize when generating mipmaps for normal map textures will make sure all resulting vector values are normalized.
It is possible to check if the image has mipmaps by calling Image.HasMipmaps or Image.GetMipmapCount. Calling Image.GenerateMipmaps on an image that already has mipmaps will replace existing mipmaps in the image.
If preserve_alpha_test_coverage is true it automatically adjusts alpha values to maintain consistent coverage when alpha testing is used. This is especially useful for hair, foliage, or other alpha-tested materials, as it prevents fading or popping artifacts across mipmap levels (LODs). This option is intended for color textures and clamps the alpha channel in the 0.0 - 1.0 range.
The alpha_test_threshold parameter is the alpha threshold used when preserving alpha test coverage across mipmap levels. The coverage is measured at mipmap 0 using the setting and the lower mipmaps are adjusted to match that coverage. Higher values preserve more detail, lower values create softer edges. Note that this threshold is independent from the Alpha Scissor Threshold set on the material and they both may need to be tuned for optimal results.
| Name | Type | Default |
|---|---|---|
renormalize | bool | — |
Errorpublic Error GenerateMipmaps(bool renormalize = false, bool preserveAlphaTestCoverage = false, float alphaTestThreshold = 0.5f);Generates mipmaps for the image. Mipmaps are precalculated lower-resolution copies of the image that are automatically used if the image needs to be scaled down when rendered. They help improve image quality and performance when rendering. This method returns an error if the image is compressed, in a custom format, or if the image's width/height is 0. Enabling renormalize when generating mipmaps for normal map textures will make sure all resulting vector values are normalized.
It is possible to check if the image has mipmaps by calling Image.HasMipmaps or Image.GetMipmapCount. Calling Image.GenerateMipmaps on an image that already has mipmaps will replace existing mipmaps in the image.
If preserve_alpha_test_coverage is true it automatically adjusts alpha values to maintain consistent coverage when alpha testing is used. This is especially useful for hair, foliage, or other alpha-tested materials, as it prevents fading or popping artifacts across mipmap levels (LODs). This option is intended for color textures and clamps the alpha channel in the 0.0 - 1.0 range.
The alpha_test_threshold parameter is the alpha threshold used when preserving alpha test coverage across mipmap levels. The coverage is measured at mipmap 0 using the setting and the lower mipmaps are adjusted to match that coverage. Higher values preserve more detail, lower values create softer edges. Note that this threshold is independent from the Alpha Scissor Threshold set on the material and they both may need to be tuned for optimal results.
| Name | Type | Default |
|---|---|---|
renormalize | bool | false |
preserveAlphaTestCoverage | bool | false |
alphaTestThreshold | float | 0.5f |
ErrorGetDatabyte[]
public byte[] GetData();Returns a copy of the image's raw data.
byte[]GetDataSizelong
public long GetDataSize();Returns size (in bytes) of the image's raw data.
longGetFormatImage.Format
public Image.Format GetFormat();Returns this image's format.
Image.FormatGetHeightint
public int GetHeight();Returns the image's height.
intGetMipmapCountint
public int GetMipmapCount();Returns the number of lower-resolution levels, excluding the base image. The tested 32×16 image has five such levels in its complete chain.
intNumber of mip levels after the base, or 0 when mipmaps are absent.
GetMipmapOffsetlong
public long GetMipmapOffset(int mipmap);Returns the offset where the image's mipmap with index mipmap is stored in the Image.Data dictionary.
| Name | Type | Default |
|---|---|---|
mipmap | int | — |
longGetPixelColor
public Color GetPixel(int x, int y);Reads a base-level Image pixel on the CPU. Supply coordinates within the image dimensions; obtain a readable representation first for a compressed format. This is not filtered shader sampling or source_color conversion.
| Name | Type | Default |
|---|---|---|
x | int | — |
y | int | — |
xInteger horizontal coordinate from 0 through width minus 1.
yInteger vertical coordinate from 0 through height minus 1.
ColorPixel Color in the Image representation, not the final lit/exposed material color.
GetPixelvColor
public Color GetPixelv(Vector2I point);Returns the color of the pixel at point.
This is the same as Image.GetPixel, but with a Vector2I argument instead of two integer arguments.
| Name | Type | Default |
|---|---|---|
point | Vector2I | — |
ColorGetRegionImage
public Image GetRegion(Rect2I region);Returns a new Image that is a copy of this Image's area specified with region.
| Name | Type | Default |
|---|---|---|
region | Rect2I | — |
ImageGetSizeVector2I
public Vector2I GetSize();Returns the image's size (width and height).
Vector2IGetUsedRectRect2I
public Rect2I GetUsedRect();Returns a Rect2I enclosing the visible portion of the image, considering each pixel with a non-zero alpha channel as visible.
Rect2IGetWidthint
public int GetWidth();Returns the image's width.
intHasMipmapsbool
public bool HasMipmaps();Reports whether the Image contains lower-resolution mip levels in addition to the base image. Does not select a material filter or enable shader sampling of those levels.
booltrue when a mipmap chain is present, otherwise false.
IsCompressedbool
public bool IsCompressed();Returns true if the image is compressed.
boolIsEmptybool
public bool IsEmpty();Returns true if the image has no data.
boolIsInvisiblebool
public bool IsInvisible();Returns true if all the image's pixels have an alpha value of 0. Returns false if any pixel has an alpha value higher than 0.
boolLinearToSrgbvoid
public void LinearToSrgb();Converts the entire image from linear encoding to nonlinear sRGB encoding. Only works on images with Image.Format.Rgb8, Image.Format.Rgba8, Image.Format.Rgbh, or Image.Format.Rgbah format.
LoadError
public Error Load(string path);Loads an image from file path. See Supported image formats for a list of supported image formats and limitations.
Warning: This method should only be used in the editor or in cases when you need to load external images at run-time, such as images located at the user:// directory, and may not work in exported projects.
See also ImageTexture description for usage examples.
| Name | Type | Default |
|---|---|---|
path | string | — |
ErrorLoadBmpFromBuffer2 overloads
public Error LoadBmpFromBuffer(byte[] buffer);Loads an image from the binary contents of a BMP file.
Note: Reckfell's BMP module doesn't support 16-bit per pixel images. Only 1-bit, 4-bit, 8-bit, 24-bit, and 32-bit per pixel images are supported.
Note: This method is only available in engine builds with the BMP module enabled. By default, the BMP module is enabled, but it can be disabled at build-time using the module_bmp_enabled=no SCons option.
| Name | Type | Default |
|---|---|---|
buffer | byte[] | — |
Errorpublic Error LoadBmpFromBuffer(ReadOnlySpan<byte> buffer);Loads an image from the binary contents of a BMP file.
Note: Reckfell's BMP module doesn't support 16-bit per pixel images. Only 1-bit, 4-bit, 8-bit, 24-bit, and 32-bit per pixel images are supported.
Note: This method is only available in engine builds with the BMP module enabled. By default, the BMP module is enabled, but it can be disabled at build-time using the module_bmp_enabled=no SCons option.
| Name | Type | Default |
|---|---|---|
buffer | ReadOnlySpan<byte> | — |
ErrorLoadDdsFromBuffer2 overloads
public Error LoadDdsFromBuffer(byte[] buffer);Loads an image from the binary contents of a DDS file.
Note: This method is only available in engine builds with the DDS module enabled. By default, the DDS module is enabled, but it can be disabled at build-time using the module_dds_enabled=no SCons option.
| Name | Type | Default |
|---|---|---|
buffer | byte[] | — |
Errorpublic Error LoadDdsFromBuffer(ReadOnlySpan<byte> buffer);Loads an image from the binary contents of a DDS file.
Note: This method is only available in engine builds with the DDS module enabled. By default, the DDS module is enabled, but it can be disabled at build-time using the module_dds_enabled=no SCons option.
| Name | Type | Default |
|---|---|---|
buffer | ReadOnlySpan<byte> | — |
ErrorLoadExrFromBuffer2 overloads
public Error LoadExrFromBuffer(byte[] buffer);Loads an image from the binary contents of an OpenEXR file.
| Name | Type | Default |
|---|---|---|
buffer | byte[] | — |
Errorpublic Error LoadExrFromBuffer(ReadOnlySpan<byte> buffer);Loads an image from the binary contents of an OpenEXR file.
| Name | Type | Default |
|---|---|---|
buffer | ReadOnlySpan<byte> | — |
ErrorLoadFromFileImage
public static Image LoadFromFile(string path);Reads the source file directly, bypassing import settings. An imported project file produces an export warning in a debug build. Use ResourceLoader for a packaged Image resource; arrange raw-file availability separately in an exported game.
| Name | Type | Default |
|---|---|---|
path | string | — |
pathAccessible path to an actual file in a supported format. An imported texture may have different dimensions or processing; this method reads the original bytes.
ImageLoaded Image, or null on a reading/decoding error. Check the result before processing.
LoadJpgFromBuffer2 overloads
public Error LoadJpgFromBuffer(byte[] buffer);Loads an image from the binary contents of a JPEG file.
| Name | Type | Default |
|---|---|---|
buffer | byte[] | — |
Errorpublic Error LoadJpgFromBuffer(ReadOnlySpan<byte> buffer);Loads an image from the binary contents of a JPEG file.
| Name | Type | Default |
|---|---|---|
buffer | ReadOnlySpan<byte> | — |
ErrorLoadKtxFromBuffer2 overloads
public Error LoadKtxFromBuffer(byte[] buffer);Loads an image from the binary contents of a KTX(https://github.com/KhronosGroup/KTX-Software) file. Unlike most image formats, KTX can store VRAM-compressed data and embed mipmaps.
Note: Reckfell's libktx implementation only supports 2D images. Cubemaps, texture arrays, and de-padding are not supported.
Note: This method is only available in engine builds with the KTX module enabled. By default, the KTX module is enabled, but it can be disabled at build-time using the module_ktx_enabled=no SCons option.
| Name | Type | Default |
|---|---|---|
buffer | byte[] | — |
Errorpublic Error LoadKtxFromBuffer(ReadOnlySpan<byte> buffer);Loads an image from the binary contents of a KTX(https://github.com/KhronosGroup/KTX-Software) file. Unlike most image formats, KTX can store VRAM-compressed data and embed mipmaps.
Note: Reckfell's libktx implementation only supports 2D images. Cubemaps, texture arrays, and de-padding are not supported.
Note: This method is only available in engine builds with the KTX module enabled. By default, the KTX module is enabled, but it can be disabled at build-time using the module_ktx_enabled=no SCons option.
| Name | Type | Default |
|---|---|---|
buffer | ReadOnlySpan<byte> | — |
ErrorLoadPngFromBuffer2 overloads
public Error LoadPngFromBuffer(byte[] buffer);Loads an image from the binary contents of a PNG file.
| Name | Type | Default |
|---|---|---|
buffer | byte[] | — |
Errorpublic Error LoadPngFromBuffer(ReadOnlySpan<byte> buffer);Loads an image from the binary contents of a PNG file.
| Name | Type | Default |
|---|---|---|
buffer | ReadOnlySpan<byte> | — |
ErrorLoadSvgFromBuffer2 overloads
public Error LoadSvgFromBuffer(byte[] buffer, float scale = 1f);Loads an image from the UTF-8 binary contents of an uncompressed SVG file (.svg).
Note: Beware when using compressed SVG files (like .svgz), they need to be decompressed before loading.
Note: This method is only available in engine builds with the SVG module enabled. By default, the SVG module is enabled, but it can be disabled at build-time using the module_svg_enabled=no SCons option.
| Name | Type | Default |
|---|---|---|
buffer | byte[] | — |
scale | float | 1f |
Errorpublic Error LoadSvgFromBuffer(ReadOnlySpan<byte> buffer, float scale);Loads an image from the UTF-8 binary contents of an uncompressed SVG file (.svg).
Note: Beware when using compressed SVG files (like .svgz), they need to be decompressed before loading.
Note: This method is only available in engine builds with the SVG module enabled. By default, the SVG module is enabled, but it can be disabled at build-time using the module_svg_enabled=no SCons option.
| Name | Type | Default |
|---|---|---|
buffer | ReadOnlySpan<byte> | — |
scale | float | — |
ErrorLoadSvgFromStringError
public Error LoadSvgFromString(string svgStr, float scale = 1f);Loads an image from the string contents of an SVG file (.svg).
Note: This method is only available in engine builds with the SVG module enabled. By default, the SVG module is enabled, but it can be disabled at build-time using the module_svg_enabled=no SCons option.
| Name | Type | Default |
|---|---|---|
svgStr | string | — |
scale | float | 1f |
ErrorLoadTgaFromBuffer2 overloads
public Error LoadTgaFromBuffer(byte[] buffer);Loads an image from the binary contents of a TGA file.
Note: This method is only available in engine builds with the TGA module enabled. By default, the TGA module is enabled, but it can be disabled at build-time using the module_tga_enabled=no SCons option.
| Name | Type | Default |
|---|---|---|
buffer | byte[] | — |
Errorpublic Error LoadTgaFromBuffer(ReadOnlySpan<byte> buffer);Loads an image from the binary contents of a TGA file.
Note: This method is only available in engine builds with the TGA module enabled. By default, the TGA module is enabled, but it can be disabled at build-time using the module_tga_enabled=no SCons option.
| Name | Type | Default |
|---|---|---|
buffer | ReadOnlySpan<byte> | — |
ErrorLoadWebpFromBuffer2 overloads
public Error LoadWebpFromBuffer(byte[] buffer);Loads an image from the binary contents of a WebP file.
| Name | Type | Default |
|---|---|---|
buffer | byte[] | — |
Errorpublic Error LoadWebpFromBuffer(ReadOnlySpan<byte> buffer);Loads an image from the binary contents of a WebP file.
| Name | Type | Default |
|---|---|---|
buffer | ReadOnlySpan<byte> | — |
ErrorNormalMapToXyvoid
public void NormalMapToXy();Converts the image's data to represent coordinates on a 3D plane. This is used when the image represents a normal map. A normal map can add lots of detail to a 3D surface without increasing the polygon count.
PremultiplyAlphavoid
public void PremultiplyAlpha();Multiplies color values with alpha values. Resulting color values for a pixel are (color * alpha)/256. See also CanvasItemMaterial.BlendMode.
Resizevoid
public void Resize(int width, int height, Image.Interpolation interpolation = Image.Interpolation.Bilinear);Resizes the image to the given width and height. New pixels are calculated using the interpolation mode defined via Image.Interpolation constants.
Note: If the image's format is Image.Format.Rgba4444, Image.Format.Rgb565, or Image.Format.Rgbe9995, it will be temporarily converted to either Image.Format.Rgba8 or Image.Format.Rgbah. This can affect the quality of the resized image.
| Name | Type | Default |
|---|---|---|
width | int | — |
height | int | — |
interpolation | Image.Interpolation | Image.Interpolation.Bilinear |
ResizeToPo2void
public void ResizeToPo2(bool square = false, Image.Interpolation interpolation = Image.Interpolation.Bilinear);Resizes the image to the nearest power of 2 for the width and height. If square is true, sets width and height to be the same. New pixels are calculated using the interpolation mode defined via Image.Interpolation constants.
| Name | Type | Default |
|---|---|---|
square | bool | false |
interpolation | Image.Interpolation | Image.Interpolation.Bilinear |
RgbeToSrgbImage
public Image RgbeToSrgb();Converts a standard linear RGBE (Red Green Blue Exponent) image to an image that uses nonlinear sRGB encoding.
ImageRotate180void
public void Rotate180();Rotates the image by 180 degrees. The width and height of the image must be greater than 1.
Rotate90void
public void Rotate90(ClockDirection direction);Rotates the image in the specified direction by 90 degrees. The width and height of the image must be greater than 1. If the width and height are not equal, the image will be resized.
| Name | Type | Default |
|---|---|---|
direction | ClockDirection | — |
SaveDdsError
public Error SaveDds(string path);Saves the image as a DDS (DirectDraw Surface) file to path. DDS is a container format that can store textures in various compression formats, such as DXT1, DXT5, or BC7. This function will return ERR_UNAVAILABLE if Reckfell was compiled without the DDS module.
Note: The DDS module may be disabled in certain builds, which means Image.SaveDds will return ERR_UNAVAILABLE when it is called from an exported project.
| Name | Type | Default |
|---|---|---|
path | string | — |
ErrorSaveDdsToBufferbyte[]
public byte[] SaveDdsToBuffer();Saves the image as a DDS (DirectDraw Surface) file to a byte array. DDS is a container format that can store textures in various compression formats, such as DXT1, DXT5, or BC7. This function will return an empty byte array if Reckfell was compiled without the DDS module.
Note: The DDS module may be disabled in certain builds, which means Image.SaveDdsToBuffer will return an empty byte array when it is called from an exported project.
byte[]SaveExr2 overloads
public Error SaveExr(string path, bool grayscale);Writes the Image to EXR, preserving negative float values without an upper clamp. Supports uncompressed R/RG/RGB/RGBA 8-bit, half-float and float data. Does not apply an sRGB transfer or tone mapping; cannot recover values lost before saving.
| Name | Type | Default |
|---|---|---|
path | string | — |
grayscale | bool | — |
pathOutput file path in a writable directory, for example user://image.exr.
grayscaleFor a single-channel image, true labels the channel as luminance Y instead of R. Does not convert RGB to grayscale.
ErrorError.Ok on successful writing; otherwise an error code. Without the corresponding writer, Error.Unavailable. Check the result before using the file.
public Error SaveExr(string path, bool grayscale = false, bool colorImage = false, float maxLinearValue = -1f);Writes the Image to EXR. colorImage clamps negative values; maxLinearValue upper-clamps channels. Supports uncompressed R/RG/RGB/RGBA 8-bit, half-float and float data. Does not apply an sRGB transfer or tone mapping; cannot recover values lost before saving.
| Name | Type | Default |
|---|---|---|
path | string | — |
grayscale | bool | false |
colorImage | bool | false |
maxLinearValue | float | -1f |
pathOutput file path in a writable directory, for example user://image.exr.
grayscaleFor a single-channel image, true labels the channel as luminance Y instead of R. Does not convert RGB to grayscale.
colorImageIf true, negative float/half-float channel values are clamped to zero. This is a data clamp, not a color-space conversion.
maxLinearValueA nonnegative value upper-clamps each written channel. A negative value, including the default -1, disables the upper clamp. This is not exposure.
ErrorError.Ok on successful writing; otherwise an error code. Without the corresponding writer, Error.Unavailable. Check the result before using the file.
SaveExrToBuffer2 overloads
public byte[] SaveExrToBuffer(bool grayscale);Saves the image as an EXR file to a byte array. If grayscale is true and the image has only one channel, it will be saved explicitly as monochrome rather than one red channel. Set color_image to true when saving a color image, such as a screenshot. Negative values will be included when color_image is false, which may be useful for saving raw floating point data such as a lightmap that includes negative light information. Color component values in the resulting EXR file will not exceed max_linear_value if max_linear_value is not negative. This function will return an empty byte array if Reckfell was compiled without the TinyEXR module.
When saving screenshots of a project that uses HDR output, use Window.GetOutputMaxLinearValue for max_linear_value.
| Name | Type | Default |
|---|---|---|
grayscale | bool | — |
byte[]public byte[] SaveExrToBuffer(bool grayscale = false, bool colorImage = false, float maxLinearValue = -1f);Saves the image as an EXR file to a byte array. If grayscale is true and the image has only one channel, it will be saved explicitly as monochrome rather than one red channel. Set color_image to true when saving a color image, such as a screenshot. Negative values will be included when color_image is false, which may be useful for saving raw floating point data such as a lightmap that includes negative light information. Color component values in the resulting EXR file will not exceed max_linear_value if max_linear_value is not negative. This function will return an empty byte array if Reckfell was compiled without the TinyEXR module.
When saving screenshots of a project that uses HDR output, use Window.GetOutputMaxLinearValue for max_linear_value.
| Name | Type | Default |
|---|---|---|
grayscale | bool | false |
colorImage | bool | false |
maxLinearValue | float | -1f |
byte[]SaveJpgError
public Error SaveJpg(string path, float quality = 0.75f);Saves the image as a JPEG file to path with the specified quality between 0.01 and 1.0 (inclusive). Higher quality values result in better-looking output at the cost of larger file sizes. Recommended quality values are between 0.75 and 0.90. Even at quality 1.00, JPEG compression remains lossy.
Note: JPEG does not save an alpha channel. If the Image contains an alpha channel, the image will still be saved, but the resulting JPEG file won't contain the alpha channel.
| Name | Type | Default |
|---|---|---|
path | string | — |
quality | float | 0.75f |
ErrorSaveJpgToBufferbyte[]
public byte[] SaveJpgToBuffer(float quality = 0.75f);Saves the image as a JPEG file to a byte array with the specified quality between 0.01 and 1.0 (inclusive). Higher quality values result in better-looking output at the cost of larger byte array sizes (and therefore memory usage). Recommended quality values are between 0.75 and 0.90. Even at quality 1.00, JPEG compression remains lossy.
Note: JPEG does not save an alpha channel. If the Image contains an alpha channel, the image will still be saved, but the resulting byte array won't contain the alpha channel.
| Name | Type | Default |
|---|---|---|
quality | float | 0.75f |
byte[]SavePngError
public Error SavePng(string path);Writes the Image to PNG. A float source is converted to an 8-bit representation, clipping values above 1. Does not tone-map the image or automatically convert linear color to sRGB. For HDR data, use a suitable float source and SaveExr.
| Name | Type | Default |
|---|---|---|
path | string | — |
pathOutput file path in a writable directory, for example user://image.png.
ErrorError.Ok on successful writing; otherwise an error code. Without the corresponding writer, Error.Unavailable. Check the result before using the file.
SavePngToBufferbyte[]
public byte[] SavePngToBuffer();Saves the image as a PNG file to a byte array.
byte[]SaveWebpError
public Error SaveWebp(string path, bool lossy = false, float quality = 0.75f);Saves the image as a WebP (Web Picture) file to the file at path. By default it will save lossless. If lossy is true, the image will be saved lossy, using the quality setting between 0.0 and 1.0 (inclusive). Lossless WebP offers more efficient compression than PNG.
Note: The WebP format is limited to a size of 16383×16383 pixels, while PNG can save larger images.
| Name | Type | Default |
|---|---|---|
path | string | — |
lossy | bool | false |
quality | float | 0.75f |
ErrorSaveWebpToBufferbyte[]
public byte[] SaveWebpToBuffer(bool lossy = false, float quality = 0.75f);Saves the image as a WebP (Web Picture) file to a byte array. By default it will save lossless. If lossy is true, the image will be saved lossy, using the quality setting between 0.0 and 1.0 (inclusive). Lossless WebP offers more efficient compression than PNG.
Note: The WebP format is limited to a size of 16383×16383 pixels, while PNG can save larger images.
| Name | Type | Default |
|---|---|---|
lossy | bool | false |
quality | float | 0.75f |
byte[]SetData2 overloads
public void SetData(int width, int height, bool useMipmaps, Image.Format format, byte[] data);Overwrites data of an existing Image. Non-static equivalent of Image.CreateFromData.
| Name | Type | Default |
|---|---|---|
width | int | — |
height | int | — |
useMipmaps | bool | — |
format | Image.Format | — |
data | byte[] | — |
public void SetData(int width, int height, bool useMipmaps, Image.Format format, ReadOnlySpan<byte> data);Overwrites data of an existing Image. Non-static equivalent of Image.CreateFromData.
| Name | Type | Default |
|---|---|---|
width | int | — |
height | int | — |
useMipmaps | bool | — |
format | Image.Format | — |
data | ReadOnlySpan<byte> | — |
SetPixelvoid
public void SetPixel(int x, int y, Color color);Sets the Color of the pixel at (x, y) to color.
int imgWidth = 10;
int imgHeight = 5;
var img = Image.Create(imgWidth, imgHeight, false, Image.Format.Rgba8);
img.SetPixel(1, 2, Colors.Red); // Sets the color at (1, 2) to red.This is the same as Image.SetPixelv, but with a two integer arguments instead of a Vector2I argument.
Note: Depending on the image's format, the color set here may be clamped or lose precision. Do not assume the color returned by Image.GetPixel to be identical to the one set here; any comparisons will likely need to use an approximation like Color.IsEqualApprox.
Note: On grayscale image formats, only the red channel of color is used (and alpha if relevant). The green and blue channels are ignored.
| Name | Type | Default |
|---|---|---|
x | int | — |
y | int | — |
color | Color | — |
SetPixelvvoid
public void SetPixelv(Vector2I point, Color color);Sets the Color of the pixel at point to color.
int imgWidth = 10;
int imgHeight = 5;
var img = Image.Create(imgWidth, imgHeight, false, Image.Format.Rgba8);
img.SetPixelv(new Vector2I(1, 2), Colors.Red); // Sets the color at (1, 2) to red.This is the same as Image.SetPixel, but with a Vector2I argument instead of two integer arguments.
Note: Depending on the image's format, the color set here may be clamped or lose precision. Do not assume the color returned by Image.GetPixelv to be identical to the one set here; any comparisons will likely need to use an approximation like Color.IsEqualApprox.
Note: On grayscale image formats, only the red channel of color is used (and alpha if relevant). The green and blue channels are ignored.
| Name | Type | Default |
|---|---|---|
point | Vector2I | — |
color | Color | — |
ShrinkX2void
public void ShrinkX2();Shrinks the image by a factor of 2 on each axis (this divides the pixel count by 4).
SrgbToLinearvoid
public void SrgbToLinear();Converts the raw data from nonlinear sRGB encoding to linear encoding. Only works on images with Image.Format.Rgb8, Image.Format.Rgba8, Image.Format.Rgbh, or Image.Format.Rgbah format.
Note: The 8-bit formats are not suitable for storing linearly encoded values; a significant amount of color information will be lost in darker values. Use this function on images that use a floating point format instead.
Fields and constants2
MaxHeightField
public const long MaxHeight = 16777216;The maximal height allowed for Image resources.
MaxWidthField
public const long MaxWidth = 16777216;The maximal width allowed for Image resources.
Image.AlphaMode
Image.AstcFormat
| Value | Description |
|---|---|
Format4X4 = 0 | Hint to indicate that the high quality 4×4 ASTC compression format should be used. |
Format8X8 = 1 | Hint to indicate that the low quality 8×8 ASTC compression format should be used. |
Image.CompressMode
Image.CompressProfile
| Value | Description |
|---|---|
Automatic = 0 | Automatically adjusts the quality level based on the number of unique color channels present in the image. For ASTC, this corresponds to picking 8×8 when only one channel is detected (R, L), 6×6 when two channels are detected (RG, LA), and 4×4 in all other cases. |
Compressed = 2 | Prioritizes some compression over quality. For ASTC, this corresponds to using a 6×6 block size. |
Max = 4 | Represents the size of the |
MaxCompression = 3 | Prioritizes highest compression over quality. For ASTC, this corresponds to using an 8×8 block size. |
MaxQuality = 1 | Prioritizes highest quality over compression. For ASTC, this corresponds to using a 4×4 block size. |
Image.CompressSource
| Value | Description |
|---|---|
Generic = 0 | Source texture (before compression) is a regular texture. Default for all textures. |
Normal = 2 | Source texture (before compression) is a normal texture (e.g. it can be compressed into two channels). |
Srgb = 1 | Source texture (before compression) uses nonlinear sRGB encoding. |
Image.Format
| Value | Description |
|---|---|
Astc4X4 = 35 | Adaptive Scalable Texture Compression. This implements the 4×4 (high quality) mode. |
Astc4X4Hdr = 36 | Same format as |
Astc6X6 = 47 | Adaptive Scalable Texture Compression. This implements the 6×6 (medium quality) mode. |
Astc6X6Hdr = 48 | Same format as |
Astc8X8 = 37 | Adaptive Scalable Texture Compression. This implements the 8×8 (low quality) mode. |
Astc8X8Hdr = 38 | Same format as |
BptcRgba = 22 | Texture format that uses BPTC(https://www.khronos.org/opengl/wiki/BPTC_Texture_Compression) compression with unsigned normalized RGBA components.
Note: When creating an |
BptcRgbf = 23 | Texture format that uses BPTC(https://www.khronos.org/opengl/wiki/BPTC_Texture_Compression) compression with signed floating-point RGB components. |
BptcRgbfu = 24 | Texture format that uses BPTC(https://www.khronos.org/opengl/wiki/BPTC_Texture_Compression) compression with unsigned floating-point RGB components. |
Dxt1 = 17 | The S3TC(https://en.wikipedia.org/wiki/S3_Texture_Compression) texture format that uses Block Compression 1, and is the smallest variation of S3TC, only providing 1 bit of alpha and color data being premultiplied with alpha.
Note: When creating an |
Dxt3 = 18 | The S3TC(https://en.wikipedia.org/wiki/S3_Texture_Compression) texture format that uses Block Compression 2, and color data is interpreted as not having been premultiplied by alpha. Well suited for images with sharp alpha transitions between translucent and opaque areas.
Note: When creating an |
Dxt5 = 19 | The S3TC(https://en.wikipedia.org/wiki/S3_Texture_Compression) texture format also known as Block Compression 3 or BC3 that contains 64 bits of alpha channel data followed by 64 bits of DXT1-encoded color data. Color data is not premultiplied by alpha, same as DXT3. DXT5 generally produces superior results for transparent gradients compared to DXT3.
Note: When creating an |
Dxt5RaAsRg = 34 | The S3TC(https://en.wikipedia.org/wiki/S3_Texture_Compression) texture format also known as Block Compression 3 or BC3, which compresses RA data and interprets it as two channels (red and green). See also |
Etc = 25 | Ericsson Texture Compression format 1, also referred to as "ETC1", and is part of the OpenGL ES graphics standard. This format cannot store an alpha channel. |
Etc2R11 = 26 | Ericsson Texture Compression format 2 ( |
Etc2R11S = 27 | Ericsson Texture Compression format 2 ( |
Etc2RaAsRg = 33 | Ericsson Texture Compression format 2 ( |
Etc2Rg11 = 28 | Ericsson Texture Compression format 2 ( |
Etc2Rg11S = 29 | Ericsson Texture Compression format 2 ( |
Etc2Rgb8 = 30 | Ericsson Texture Compression format 2 ( |
Etc2Rgb8A1 = 32 | Ericsson Texture Compression format 2 ( |
Etc2Rgba8 = 31 | Ericsson Texture Compression format 2 ( |
L8 = 0 | Texture format with a single 8-bit depth representing luminance. |
La8 = 1 | OpenGL texture format with two values, luminance and alpha each stored with 8 bits. |
Max = 49 | Represents the size of the |
R16 = 39 | OpenGL texture format |
R16I = 43 | OpenGL texture format |
R8 = 2 | OpenGL texture format |
Rf = 8 | OpenGL texture format |
Rg16 = 40 | OpenGL texture format |
Rg16I = 44 | OpenGL texture format |
Rg8 = 3 | OpenGL texture format |
Rgb16 = 41 | OpenGL texture format |
Rgb16I = 45 | OpenGL texture format |
Rgb565 = 7 | OpenGL texture format |
Rgb8 = 4 | OpenGL texture format |
Rgba16 = 42 | OpenGL texture format |
Rgba16I = 46 | OpenGL texture format |
Rgba4444 = 6 | OpenGL texture format |
Rgba8 = 5 | OpenGL texture format |
Rgbaf = 11 | OpenGL texture format |
Rgbah = 15 | OpenGL texture format |
Rgbe9995 = 16 | A special OpenGL texture format where the three color components have 9 bits of precision and all three share a single 5-bit exponent. |
Rgbf = 10 | OpenGL texture format |
Rgbh = 14 | OpenGL texture format |
Rgf = 9 | OpenGL texture format |
Rgh = 13 | OpenGL texture format |
RgtcR = 20 | Texture format that uses Red Green Texture Compression, normalizing the red channel data using the same compression algorithm that DXT5 uses for the alpha channel. |
RgtcRg = 21 | Texture format that uses Red Green Texture Compression, normalizing the red and green channel data using the same compression algorithm that DXT5 uses for the alpha channel. |
Rh = 12 | OpenGL texture format |
Image.Interpolation
| Value | Description |
|---|---|
Bilinear = 1 | Performs bilinear interpolation. If the image is resized, it will be blurry. This mode is faster than |
Cubic = 2 | Performs cubic interpolation. If the image is resized, it will be blurry. This mode often gives better results compared to |
Lanczos = 4 | Performs Lanczos interpolation. This is the slowest image resizing mode, but it typically gives the best results, especially when downscaling images. |
Nearest = 0 | Performs nearest-neighbor interpolation. If the image is resized, it will be pixelated. |
Trilinear = 3 | Performs bilinear separately on the two most-suited mipmap levels, then linearly interpolates between them.
It's slower than |
Image.UsedChannels
| Value | Description |
|---|---|
L = 0 | The image only uses one channel for luminance (grayscale). |
La = 1 | The image uses two channels for luminance and alpha, respectively. |
R = 2 | The image only uses the red channel. |
Rg = 3 | The image uses two channels for red and green. |
Rgb = 4 | The image uses three channels for red, green, and blue. |
Rgba = 5 | The image uses four channels for red, green, blue, and alpha. |