Class ImageFileSettings

Encapsulates all configuration options that govern image encoding and decoding operations performed by ScyllaFileUtil.

Settings are divided into two concerns:

• Encoding - Format, Quality, and EXRFlags control how a Texture2D is serialized to bytes when saving an image file.
• Decoding - GenerateMipMaps, MakeReadable, FilterMode, WrapMode, and AnisoLevel control how bytes are deserialized into a Texture2D when loading an image file.

Several static preset properties are provided for common scenarios. These presets return shared singleton instances; do not mutate them directly. Use Clone() to create a mutable copy when you need to adjust a preset.

Inheritance

object

ImageFileSettings

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Namespace: Scylla.Core.Util.File

Assembly: ScyllaCore.dll

Syntax

public sealed class ImageFileSettings

Constructors

ImageFileSettings()

Initializes a new instance of the ImageFileSettings class with all properties set to their default values: PNG format, quality DEFAULT_QUALITY (90), no mipmap generation, readable output, bilinear filtering, clamp wrap mode, aniso level 1, and no EXR flags.

Declaration

public ImageFileSettings()

ImageFileSettings(ImageFileSettings)

Initializes a new instance of the ImageFileSettings class by performing a shallow copy of all properties from other.

Declaration

public ImageFileSettings(ImageFileSettings other)

Parameters

Type	Name	Description
ImageFileSettings	other	The ImageFileSettings instance to copy. When null, the new instance retains all default property values as if the parameterless constructor had been called.

Fields

DEFAULT_QUALITY

The default quality value applied to lossy formats (JPG, WEBP) when no explicit quality is specified. Equals 90, providing a good balance between image fidelity and file size for most use cases.

Declaration

public const int DEFAULT_QUALITY = 90

Field Value

Type	Description
int

MAX_QUALITY

The maximum permitted value for Quality. Equals 100. Values above this threshold cause Validate() to throw a FileException.

Declaration

public const int MAX_QUALITY = 100

Field Value

Type	Description
int

MIN_QUALITY

The minimum permitted value for Quality. Equals 1. Values below this threshold cause Validate() to throw a FileException.

Declaration

public const int MIN_QUALITY = 1

Field Value

Type	Description
int

Properties

AnisoLevel

Gets or sets the anisotropic filtering level applied to the texture created during decoding. Valid range is 0-16. Defaults to 1.

A value of 0 disables anisotropic filtering. Higher values improve texture sharpness when the surface is viewed at oblique angles, at the cost of additional GPU work. Values outside the 0-16 range cause Validate() to throw a FileException.

Declaration

public int AnisoLevel { get; set; }

Property Value

Type	Description
int

Default

Gets the default settings: PNG format, DEFAULT_QUALITY (90), no mipmap generation, readable texture, bilinear filtering, clamp wrap mode, and aniso level 1.

This preset is used as the fallback whenever null is passed to any ScyllaFileUtil image method. Do not mutate this instance; call Clone() to obtain a mutable copy.

Declaration

public static ImageFileSettings Default { get; }

Property Value

Type	Description
ImageFileSettings

EXRFlags

Gets or sets the EXR compression flags used when encoding to EXR. Defaults to Texture2D.EXRFlags.None (uncompressed).

This property is only meaningful when Format is EXR; it has no effect for other formats. Common values include Texture2D.EXRFlags.CompressZIP for lossless ZIP compression and Texture2D.EXRFlags.OutputAsFloat to force 32-bit float precision instead of 16-bit half-float.

Declaration

public Texture2D.EXRFlags EXRFlags { get; set; }

Property Value

Type	Description
Texture2D.EXRFlags

FastCompression

Gets settings for fast, smaller-file-size JPEG output at quality 75. Uses JPG and Quality 75.

Suitable for photographic content where a reduced file size is more important than pixel-perfect fidelity. Does not support transparency.

Declaration

public static ImageFileSettings FastCompression { get; }

Property Value

Type	Description
ImageFileSettings

FilterMode

Gets or sets the texture filtering mode applied to the texture created during decoding. Defaults to UnityEngine.FilterMode.Bilinear.

UnityEngine.FilterMode.Point is appropriate for pixel-art or grid-aligned textures where bilinear interpolation would blur edges. UnityEngine.FilterMode.Trilinear adds cross-mipmap filtering and is only meaningful when GenerateMipMaps is true.

Declaration

public FilterMode FilterMode { get; set; }

Property Value

Type	Description
FilterMode

Format

Gets or sets the image file format used when encoding a texture to bytes. Defaults to PNG.

When null settings are passed to a ScyllaFileUtil save method, the format may additionally be inferred from the file path extension before this property takes effect.

Declaration

public ImageFileFormat Format { get; set; }

Property Value

Type	Description
ImageFileFormat

See Also

ImageFileFormat

GenerateMipMaps

Gets or sets whether mipmaps are generated for the texture created during decoding. Defaults to false.

Enable this when the loaded texture will be rendered at varying distances and benefits from hardware mip filtering. Mipmap generation increases memory usage and load time, so leave it disabled for UI textures or single-resolution assets.

Declaration

public bool GenerateMipMaps { get; set; }

Property Value

Type	Description
bool

HDR

Gets settings for high dynamic range image output using EXR format with ZIP compression. Uses EXR and EXRFlags set to Texture2D.EXRFlags.CompressZIP.

Suitable for HDR render captures, environment maps, and linear color space workflows where the full floating-point precision of the source texture must be preserved. ZIP compression is lossless and significantly reduces file size compared to uncompressed EXR.

Declaration

public static ImageFileSettings HDR { get; }

Property Value

Type	Description
ImageFileSettings

HighQuality

Gets settings for maximum-fidelity PNG output with mipmap generation enabled. Uses PNG, MAX_QUALITY (100), and GenerateMipMaps set to true.

Suitable for texture assets that will be rendered at varying distances and benefit from pre-generated mipmaps. Note that the Quality property has no effect on PNG, which is always lossless.

Declaration

public static ImageFileSettings HighQuality { get; }

Property Value

Type	Description
ImageFileSettings

MakeReadable

Gets or sets whether the texture created during decoding is marked as CPU-readable. Defaults to true.

When true, pixel data can be read back from the GPU via Texture2D.GetPixels and related methods after loading. Set to false when the texture will only be sampled by the GPU (e.g., render targets or screenshot output), which avoids keeping a redundant CPU-side copy.

Declaration

public bool MakeReadable { get; set; }

Property Value

Type	Description
bool

Quality

Gets or sets the encoding quality for lossy formats (JPG and WEBP). Valid range is [MIN_QUALITY, MAX_QUALITY] (1-100). Defaults to DEFAULT_QUALITY (90).

Higher values preserve more image detail at the cost of larger file sizes. This property has no effect on lossless formats (PNG, TGA) or on EXR, which uses EXRFlags to control compression instead.

Declaration

public int Quality { get; set; }

Property Value

Type	Description
int

Screenshot

Gets settings for screenshot capture: PNG format with MakeReadable set to false.

The non-readable flag prevents an unnecessary GPU-to-CPU data readback since screenshots are saved directly from encoded bytes without further pixel access. Use this preset with SaveImage(string, Texture2D, ImageFileSettings).

Declaration

public static ImageFileSettings Screenshot { get; }

Property Value

Type	Description
ImageFileSettings

WebOptimized

Gets settings optimized for web delivery using WEBP format at quality 80. Uses WEBP and Quality 80.

WEBP typically produces smaller files than both PNG and JPEG at equivalent quality levels while retaining alpha channel support. Requires Unity 2021.2 or later; check IsImageFormatSupported(ImageFileFormat) before use.

Declaration

public static ImageFileSettings WebOptimized { get; }

Property Value

Type	Description
ImageFileSettings

WrapMode

Gets or sets the texture coordinate wrap mode applied to the texture created during decoding. Defaults to UnityEngine.TextureWrapMode.Clamp.

Use UnityEngine.TextureWrapMode.Repeat for seamlessly tiling textures. UnityEngine.TextureWrapMode.Clamp is the safe default for most UI and sprite textures to prevent edge bleeding.

Declaration

public TextureWrapMode WrapMode { get; set; }

Property Value

Type	Description
TextureWrapMode

Methods

Clone()

Creates a deep copy of this ImageFileSettings instance with all property values preserved.

Declaration

public ImageFileSettings Clone()

Returns

Type	Description
ImageFileSettings	A new ImageFileSettings instance whose properties are identical to those of this instance.

Remarks

Use this method to safely derive a customized version of a preset without modifying the shared preset instance. For example:

var settings = ImageFileSettings.HighQuality.Clone();
settings.WrapMode = TextureWrapMode.Repeat;

Validate()

Validates all properties and throws a FileException if any value is outside its permitted range.

Declaration

public void Validate()

Remarks

The following constraints are enforced:

• Quality must be in the range [MIN_QUALITY, MAX_QUALITY] (1-100).
• AnisoLevel must be in the range 0-16.

This method is called automatically by ScyllaFileUtil before encoding or decoding begins; callers do not typically need to invoke it manually.

Exceptions

Type	Condition
FileException	Thrown with InvalidSettings when Quality is outside [1, 100] or AnisoLevel is outside [0, 16].

Extension Methods

FileExtensions.SaveSecureToFileAsync<T>(T, string, string, CancellationToken)

FileExtensions.SaveSecureToFile<T>(T, string, string)

FileExtensions.SaveToFileAsync<T>(T, string, CancellationToken)

FileExtensions.SaveToFile<T>(T, string)

FileExtensions.SaveToFile<T>(T, string, SerializationSettings)

See Also

ImageFileFormat

ScyllaFileUtil