Editor utility that extracts or composes texture channels from image files for importing into the editor. It decodes images to RGBA using Skia or the engine decoder, converts individual channels to greyscale or normal/height maps, encodes PNGs, composes sky panoramas from cube faces, and processes batches in parallel with a memory admission system.
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading;
using System.Threading.Tasks;
using Sandbox;
using SkiaSharp;
namespace ImportUnityPackage;
/// <summary>
/// CPU image work only. Every worker owns its decoder, bitmaps and pixel buffers. Pixels stay as 8-bit RGBA bytes from
/// decoding to encoding, single channels are written as greyscale PNGs, and PNGs use fast compression: the engine's
/// float color arrays and default PNG compression made this most of a texture-heavy import's time.
/// </summary>
public static class TextureChannels
{
/// <summary>Parallel images: 80% of the logical processors, leaving the rest for the editor.</summary>
public static int WorkerLimit => Math.Max( 1, (int)(Environment.ProcessorCount * 0.8) );
/// <summary>Estimated working-set budget: a quarter of the memory available to the process, between 1 and 8 GiB.</summary>
public static long MemoryBudget => Math.Clamp( GC.GetGCMemoryInfo().TotalAvailableMemoryBytes / 4, 1L << 30, 8L << 30 );
public static void ExtractBatch( IReadOnlyList<TextureChannelRequest> requests, CancellationToken cancel )
=> ProcessBatch( requests, cancel );
public sealed record BatchStats( int Decodes, int Channels, int PeakWorkers, long PeakReservedBytes, long ElapsedMilliseconds );
/// <summary>Processes the requests in parallel. A workers or budget of 0 uses <see cref="WorkerLimit"/> or <see cref="MemoryBudget"/>.</summary>
public static BatchStats ProcessBatch( IReadOnlyList<TextureChannelRequest> requests, CancellationToken cancel, int workers = 0, long budget = 0 )
{
var workerCount = workers == 0 ? WorkerLimit : workers;
var memory = budget == 0 ? MemoryBudget : budget;
if ( workerCount < 1 || workerCount > Math.Max( WorkerLimit, 2 ) || memory <= 0 ) throw new ArgumentOutOfRangeException();
var timer = System.Diagnostics.Stopwatch.StartNew();
var gate = new object();
long reserved = 0, peakReserved = 0;
int active = 0, peakWorkers = 0, decodes = 0;
var groups = requests.Where( r => r.Faces == null ).GroupBy( r => r.Source, StringComparer.OrdinalIgnoreCase ).Select( g => g.ToArray() ).ToArray();
// A source that cannot be processed gets neutral placeholders, so one bad image does not stop the import; the
// failures are thrown together once every other image is done.
var failures = new System.Collections.Concurrent.ConcurrentBag<TextureBatchException.Failure>();
void Fail( IEnumerable<TextureChannelRequest> failed, Exception ex )
{
foreach ( var request in failed )
{
failures.Add( new( request.Source, request.Destination, ex.Message ) );
try { File.WriteAllBytes( request.Destination, Placeholder( request ) ); }
catch ( IOException ) { }
}
}
Parallel.ForEach( groups, new ParallelOptions { MaxDegreeOfParallelism = workerCount, CancellationToken = cancel }, group =>
{
// Unknown codecs and images larger than the admission budget run exclusively.
// This is an estimated working-set budget, not a hard cap on native allocations.
long reservation;
try { reservation = Math.Min( memory, EstimateMemory( group[0].Source, memory ) ); }
catch ( IOException ) { reservation = memory; } // An unreadable header runs exclusively; decoding reports it.
lock ( gate )
{
while ( reserved + reservation > memory ) { cancel.ThrowIfCancellationRequested(); Monitor.Wait( gate, 50 ); }
cancel.ThrowIfCancellationRequested();
reserved += reservation;
peakReserved = Math.Max( reserved, peakReserved );
peakWorkers = Math.Max( ++active, peakWorkers );
}
var written = new List<TextureChannelRequest>();
try
{
using var source = DecodeRgba( group[0].Source, cancel );
Interlocked.Increment( ref decodes );
foreach ( var request in group )
{
cancel.ThrowIfCancellationRequested();
File.WriteAllBytes( request.Destination, Process( source, request, cancel ) );
written.Add( request );
}
}
catch ( OperationCanceledException ) { throw; }
catch ( Exception ex ) { Fail( group.Except( written ), ex ); }
finally { lock ( gate ) { reserved -= reservation; active--; Monitor.PulseAll( gate ); } }
} );
// Sky panoramas read several sources each; they run one at a time after the channel work.
foreach ( var request in requests.Where( r => r.Faces != null ) )
{
try { decodes += ComposeSky( request, cancel ); }
catch ( OperationCanceledException ) { throw; }
catch ( Exception ex ) { Fail( new[] { request }, ex ); }
}
if ( !failures.IsEmpty ) throw new TextureBatchException( failures.OrderBy( f => f.Destination, StringComparer.OrdinalIgnoreCase ).ToArray() );
return new( decodes, requests.Count, peakWorkers, peakReserved, timer.ElapsedMilliseconds );
}
/// <summary>One request's PNG from the decoded source, resized first when the request sets a size.</summary>
static byte[] Process( SKBitmap source, TextureChannelRequest request, CancellationToken cancel )
{
var resize = request.Width > 0 && request.Height > 0 && (request.Width != source.Width || request.Height != source.Height);
// The same resampling as the engine's Bitmap.Resize.
using var resized = resize ? source.Resize( new SKImageInfo( request.Width, request.Height, SKColorType.Rgba8888, SKAlphaType.Unpremul ),
new SKSamplingOptions( SKFilterMode.Linear, SKMipmapMode.Linear ) ) : null;
var image = resized ?? source;
if ( request.Channel == -1 ) return Encode( image );
if ( request.Channel >= 0 )
{
using var gray = new SKBitmap( image.Width, image.Height, SKColorType.Gray8, SKAlphaType.Opaque );
ConvertChannel( image.GetPixelSpan(), gray.GetPixelSpan(), request.Channel, request.Scale, request.Invert, cancel );
return Encode( gray );
}
using var output = new SKBitmap( image.Width, image.Height, SKColorType.Rgba8888, SKAlphaType.Unpremul );
if ( request.Channel == -3 ) FlipGreen( image.GetPixelSpan(), output.GetPixelSpan() );
else HeightToNormal( image.GetPixelSpan(), output.GetPixelSpan(), image.Width, image.Height, request.Scale, request.Invert );
return Encode( output );
}
/// <summary>
/// A neutral 1×1 PNG for an output whose source could not be processed: a flat normal for normal maps, mid-grey for
/// roughness (an inverted smoothness channel), black for metalness (red) and height (blue), white for color,
/// occlusion (green) and opacity (alpha), as Unity's default texture is white.
/// </summary>
static byte[] Placeholder( TextureChannelRequest request )
{
using var bitmap = new SKBitmap( 1, 1, SKColorType.Rgba8888, SKAlphaType.Unpremul );
bitmap.SetPixel( 0, 0, request.Channel switch
{
-3 or -4 => new SKColor( 128, 128, 255 ),
>= 0 when request.Invert => new SKColor( 128, 128, 128 ),
0 or 2 => SKColors.Black,
_ => SKColors.White,
} );
return Encode( bitmap );
}
static byte[] Encode( SKBitmap bitmap )
{
using var stream = new SKDynamicMemoryWStream();
using var pixmap = bitmap.PeekPixels();
// zlib level 3: about half the time of the default level 6 for 10-20% larger files.
if ( pixmap == null || !pixmap.Encode( stream, new SKPngEncoderOptions( SKPngEncoderFilterFlags.AllFilters, 3 ) ) ) throw new InvalidDataException( "PNG encoding failed." );
using var data = stream.DetachAsData();
return data.ToArray();
}
/// <summary>
/// The image as 8-bit RGBA: Skia decodes PNG, JPEG, BMP and WebP directly; TGA, PSD, TIFF and the engine's other
/// formats go through the engine's decoder.
/// </summary>
static SKBitmap DecodeRgba( string source, CancellationToken cancel )
{
cancel.ThrowIfCancellationRequested();
var bytes = File.ReadAllBytes( source );
var info = default( SKImageInfo );
using ( var codec = SKCodec.Create( new SKMemoryStream( bytes ) ) )
{
if ( codec != null )
{
info = new SKImageInfo( codec.Info.Width, codec.Info.Height, SKColorType.Rgba8888, SKAlphaType.Unpremul );
if ( SKBitmap.Decode( codec, info ) is { } decoded ) return decoded;
}
}
using var bitmap = Bitmap.CreateFromBytes( bytes ) ?? throw new InvalidDataException( "Unable to decode packed texture: " + source );
var colors = bitmap.GetPixels32();
var result = new SKBitmap( bitmap.Width, bitmap.Height, SKColorType.Rgba8888, SKAlphaType.Unpremul );
var pixels = result.GetPixelSpan();
for ( var i = 0; i < colors.Length; i++ )
{
pixels[i * 4] = colors[i].r; pixels[i * 4 + 1] = colors[i].g; pixels[i * 4 + 2] = colors[i].b; pixels[i * 4 + 3] = colors[i].a;
}
return result;
}
/// <summary>
/// Composes a latitude-longitude panorama in Unity's layout from six cube faces (+X, −X, +Y, −Y, +Z, −Z), sampling
/// each face bilinearly. The panorama is four face widths wide (a power of two, at most 4096) unless Width is set.
/// </summary>
static int ComposeSky( TextureChannelRequest request, CancellationToken cancel )
{
var images = new Dictionary<string, (Color[] Pixels, int Width, int Height)>( StringComparer.OrdinalIgnoreCase );
foreach ( var source in request.Faces.Select( f => f.Source ).Distinct( StringComparer.OrdinalIgnoreCase ) )
{
cancel.ThrowIfCancellationRequested();
using var bitmap = Bitmap.CreateFromBytes( File.ReadAllBytes( source ) ) ?? throw new InvalidDataException( "Unable to decode sky face: " + source );
images[source] = (bitmap.GetPixels(), bitmap.Width, bitmap.Height);
}
var faces = request.Faces.Select( f =>
{
var image = images[f.Source];
return f.Width > 0 ? (image.Pixels, Stride: image.Width, f.X, f.Y, f.Width, f.Height, f.Flip) : (image.Pixels, Stride: image.Width, 0, 0, image.Width, image.Height, f.Flip);
} ).ToArray();
var faceSize = faces.Max( f => Math.Max( f.Item5, f.Item6 ) );
var width = request.Width > 0 ? request.Width : Math.Min( 4096, UnityImageSize.NearestPowerOfTwo( 4 * faceSize ) );
var height = width / 2;
var output = new Color[width * height];
Parallel.For( 0, height, new ParallelOptions { MaxDegreeOfParallelism = WorkerLimit, CancellationToken = cancel }, y =>
{
for ( var x = 0; x < width; x++ )
{
var (index, u, v) = UnitySky.Sample( (x + 0.5) / width, (y + 0.5) / height );
var (pixels, stride, left, top, w, h, flip) = faces[index];
if ( flip ) { u = 1 - u; v = 1 - v; }
// Bilinear, clamped inside the face's rectangle.
var fx = Math.Clamp( u * w - 0.5, 0, w - 1 );
var fy = Math.Clamp( v * h - 0.5, 0, h - 1 );
int x0 = (int)fx, y0 = (int)fy, x1 = Math.Min( x0 + 1, w - 1 ), y1 = Math.Min( y0 + 1, h - 1 );
float tx = (float)(fx - x0), ty = (float)(fy - y0);
Color At( int px, int py ) => pixels[(top + py) * stride + left + px];
var a = Color.Lerp( At( x0, y0 ), At( x1, y0 ), tx );
var b = Color.Lerp( At( x0, y1 ), At( x1, y1 ), tx );
var c = Color.Lerp( a, b, ty );
output[y * width + x] = c.WithAlpha( 1 );
}
} );
using var panorama = new Bitmap( width, height );
panorama.SetPixels( output );
File.WriteAllBytes( request.Destination, panorama.ToPng() );
return images.Count;
}
static long EstimateMemory( string source, long unknown )
{
// Skia reads PNG, JPEG and WebP headers; the importer's own reader covers TGA, PSD and TIFF. Skia closes the stream
// when it cannot read it, so the file length comes from the file system.
var length = new FileInfo( source ).Length;
using var stream = File.OpenRead( source );
using var codec = SKCodec.Create( stream );
var size = codec != null ? (codec.Info.Width, codec.Info.Height) : UnityImageSize.Read( source );
if ( size is not var (width, height) ) return unknown;
// Decoded RGBA, a resized copy, an output image, encoder buffers and compressed input; engine-decoded formats
// also hold the engine's bitmap and its 32-bit color array while converting.
return checked( (long)width * height * (codec != null ? 16 : 28) + length * 2 + 16 * 1024 * 1024 );
}
// One channel of one image, without batching: the reference output for the batch checks.
public static byte[] Extract( string source, int channel, double scale, bool invert, CancellationToken cancel )
{
using var bitmap = DecodeRgba( source, cancel );
return Process( bitmap, new TextureChannelRequest( source, null, channel, scale, invert ), cancel );
}
// A DirectX-style normal map (green down) as the OpenGL style Unity and s&box use.
static void FlipGreen( ReadOnlySpan<byte> source, Span<byte> output )
{
source.CopyTo( output );
for ( var i = 1; i < output.Length; i += 4 ) output[i] = (byte)(255 - output[i]);
}
/// <summary>
/// Unity's Create from Grayscale: the image's luminance as height, its slopes as an OpenGL-style normal map. Bumpiness
/// scales the slopes (Unity's default is 0.25); Sobel averages the slopes over the neighbouring rows and columns. An
/// approximation of Unity's filter, which is not documented exactly.
/// </summary>
static void HeightToNormal( ReadOnlySpan<byte> source, Span<byte> output, int width, int height, double bumpiness, bool sobel )
{
var heights = new float[width * height];
for ( var i = 0; i < heights.Length; i++ ) heights[i] = (0.299f * source[i * 4] + 0.587f * source[i * 4 + 1] + 0.114f * source[i * 4 + 2]) / 255f;
float H( int x, int y ) => heights[((y % height + height) % height) * width + (x % width + width) % width];
var strength = (float)(bumpiness * 64);
for ( var y = 0; y < height; y++ )
for ( var x = 0; x < width; x++ )
{
// Rows run down the image, so the slope toward the image top is H(row - 1) - H(row + 1).
float dx = H( x + 1, y ) - H( x - 1, y ), dy = H( x, y - 1 ) - H( x, y + 1 );
if ( sobel )
{
dx = (dx * 2 + H( x + 1, y - 1 ) - H( x - 1, y - 1 ) + H( x + 1, y + 1 ) - H( x - 1, y + 1 )) / 4;
dy = (dy * 2 + H( x - 1, y - 1 ) - H( x - 1, y + 1 ) + H( x + 1, y - 1 ) - H( x + 1, y + 1 )) / 4;
}
var n = new Vector3( -dx * strength / 2, -dy * strength / 2, 1 ).Normal;
var at = (y * width + x) * 4;
output[at] = Byte( n.x * 0.5f + 0.5f ); output[at + 1] = Byte( n.y * 0.5f + 0.5f ); output[at + 2] = Byte( n.z * 0.5f + 0.5f ); output[at + 3] = 255;
}
}
static byte Byte( float value ) => (byte)Math.Clamp( MathF.Round( value * 255 ), 0, 255 );
static void ConvertChannel( ReadOnlySpan<byte> source, Span<byte> output, int channel, double scale, bool invert, CancellationToken cancel )
{
// Every byte value maps to one output value, so the conversion is a table lookup.
Span<byte> table = stackalloc byte[256];
for ( var v = 0; v < 256; v++ )
{
var value = (float)Math.Clamp( v / 255.0 * scale, 0, 1 );
// Inverted channels are roughness from smoothness. s&box renders a pure white roughness texel mirror-smooth, so
// fully rough stops at 254/255.
if ( invert ) value = Math.Min( 1 - value, 254f / 255f );
table[v] = Byte( value );
}
var offset = Math.Clamp( channel, 0, 3 );
for ( var i = 0; i < output.Length; i++ )
{
if ( (i & 0xFFFF) == 0 ) cancel.ThrowIfCancellationRequested();
output[i] = table[source[i * 4 + offset]];
}
}
}