diff --git a/.gitattributes b/.gitattributes index 7de2c1597..031420e53 100644 --- a/.gitattributes +++ b/.gitattributes @@ -84,12 +84,15 @@ # treat as binary ############################################################################### *.basis binary +*.a binary *.dll binary +*.dylib binary *.exe binary *.pdf binary *.ppt binary *.pptx binary *.pvr binary +*.so binary *.snk binary *.xls binary *.xlsx binary diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 000000000..5f9f69435 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,3 @@ +# GitHub Copilot Instructions + +Read and follow [AGENTS.md](../AGENTS.md) as the repository-wide source of coding, performance, and verification requirements. Prefer existing local patterns and repository configuration whenever generated code or suggestions are accepted. diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..814e3ce26 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,41 @@ +# Six Labors AI Coding Guidelines + +These instructions apply to the entire repository. More-specific `AGENTS.md` files may add to or override them for their directory tree. + +## Working Practices + +- Inspect the relevant implementation, tests, benchmarks, project files, and nearby code before proposing or making changes. Do not infer current behavior when the source is available. +- Make the smallest complete change that solves the requested problem. Avoid unrelated cleanup, speculative abstractions, and formatting churn. +- Match established architecture, naming, formatting, documentation, and test patterns. Treat `.editorconfig`, analyzers, and repository build settings as authoritative. +- Preserve public API and observable behavior unless the task explicitly requires a change. Public API documentation must describe observable behavior, not implementation details. +- Do not use reflection against built assemblies, ad hoc assembly loading, or temporary probe projects unless explicitly requested. +- Build .NET projects in Release configuration unless explicitly instructed otherwise. + +## Performance + +- Treat throughput, latency, memory use, and binary size as design constraints, especially in pixel-processing, drawing, parsing, encoding, and other hot paths. +- Avoid unnecessary allocations, copies, boxing, closures, interface dispatch, repeated enumeration, and extra passes over data. +- Reuse the repository's existing memory ownership, pooling, span, vectorization, and parallelization patterns. Do not introduce a new mechanism when an established one fits. +- Keep hot loops simple and bounds-check-friendly. Hoist invariant work, preserve locality, and use the narrowest suitable data types without sacrificing correctness. +- Do not trade correctness or maintainability for assumed speed. Support non-obvious optimizations with measurements or clear evidence, and add or update benchmarks when performance is the purpose of the change. +- Consider all supported target frameworks and runtime capabilities. Do not regress fallback paths while optimizing newer runtimes. + +## C# Conventions + +- Follow the existing code around the change; local patterns take precedence over generic preferences. +- Do not use `record` or `record struct` types. +- Prefer established invariants over redundant guards. Validate at real external boundaries and do not add defensive checks for internally controlled states. +- Do not extract single-use helpers merely to name a block. Extract only for genuine reuse, an established local pattern, or meaningful complexity reduction. +- Add vertical whitespace after multi-line statements and declarations and between distinct logical stages. Never add trailing whitespace. +- Document every method, constructor, and property, regardless of whether it is public, internal, protected, or private. Keep public API documentation limited to observable behavior; use private and internal documentation to capture the contract and intent needed to maintain the code. +- Add inline comments throughout complex code. Explain algorithms, formulas, invariants, ownership, compatibility behavior, and performance tradeoffs at the operations and decisions they govern. Explain why the code is shaped that way rather than narrating the syntax. +- Document SIMD code especially thoroughly. Explain the vector layout, lane meaning, widening or narrowing, masks, shuffles, constants, alignment or remainder handling, supported instruction paths, scalar equivalence, and the reason each non-obvious operation is correct. +- Write algorithm and SIMD comments for a maintainer who is unfamiliar with the implementation. The reader should not need to reconstruct intent from external documentation, issue history, or benchmark results. + +## Verification + +- Add or update focused tests when behavior changes, following the test framework and conventions already used by the project. +- Never hack, weaken, skip, conditionally bypass, or otherwise manipulate a test to make it pass. Fix the production defect or the genuine test defect while preserving the test's intended coverage and sensitivity. +- Do not update golden files, reference images, snapshots, baselines, or expected-output artifacts to resolve a test failure. Treat a mismatch as evidence to investigate and correct the implementation. +- Run the narrowest relevant formatting, test, and Release build commands, then expand verification in proportion to the risk and scope of the change. +- Report what changed, the verification performed, and any remaining risks or unverified assumptions. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..5f08a449a --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,3 @@ +# Claude Code Instructions + +Read and follow [AGENTS.md](AGENTS.md) as the repository-wide source of coding, performance, and verification requirements. Apply any more-specific `AGENTS.md` or `CLAUDE.md` found below the files being changed. diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 000000000..b621d2652 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,3 @@ +# Gemini CLI Instructions + +Read and follow [AGENTS.md](AGENTS.md) as the repository-wide source of coding, performance, and verification requirements. Apply any more-specific `AGENTS.md` or `GEMINI.md` found below the files being changed. diff --git a/src/ImageSharp/Advanced/AotCompilerTools.cs b/src/ImageSharp/Advanced/AotCompilerTools.cs index 6d37fd5ce..2d893e406 100644 --- a/src/ImageSharp/Advanced/AotCompilerTools.cs +++ b/src/ImageSharp/Advanced/AotCompilerTools.cs @@ -7,8 +7,10 @@ using System.Numerics; using System.Runtime.CompilerServices; using SixLabors.ImageSharp.Formats; using SixLabors.ImageSharp.Formats.Bmp; +using SixLabors.ImageSharp.Formats.Cur; using SixLabors.ImageSharp.Formats.Exr; using SixLabors.ImageSharp.Formats.Gif; +using SixLabors.ImageSharp.Formats.Ico; using SixLabors.ImageSharp.Formats.Jpeg; using SixLabors.ImageSharp.Formats.Jpeg.Components; using SixLabors.ImageSharp.Formats.Jpeg.Components.Decoder; @@ -128,6 +130,67 @@ internal static class AotCompilerTools throw new InvalidOperationException("This method is used for AOT code generation only. Do not call it at runtime."); } + /// + /// Seeds the modern .NET AOT compiler with bulk pixel operations for every built-in pixel format. + /// + /// + /// This method is used for AOT code generation only. Do not call it at runtime. + /// + [Preserve] + public static void SeedPixelOperations() + { + try + { + // Keep this inventory finite and explicit. ImageSharp cannot precompile consumer-defined pixel types, while + // these closed calls make every built-in specialization visible without retaining the much larger legacy seed graph. + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + AotCompilePixelOperations(); + } + catch + { + // The calls only need to exist in IL; this method must never contribute a runtime execution path. + } + + throw new InvalidOperationException("This method is used for AOT code generation only. Do not call it at runtime."); + } + /// /// Seeds the compiler using the given pixel format. /// @@ -138,6 +201,7 @@ internal static class AotCompilerTools { // This is we actually call all the individual methods you need to seed. AotCompileImage(); + AotCompilePixelOperations(); AotCompileImageProcessingContextFactory(); AotCompileImageEncoderInternals(); AotCompileImageDecoderInternals(); @@ -158,6 +222,68 @@ internal static class AotCompilerTools // TODO: Do the discovery work to figure out what works and what doesn't. } + /// + /// Seeds the selected methods required by Mono WASM AOT. + /// + /// The pixel format. + [Preserve] + private static void AotCompilePixelOperations() + where TPixel : unmanaged, IPixel + { + // These default arguments are never consumed. Direct calls are required so the IL contains the exact closed + // MethodSpecs that Mono WASM AOT can otherwise miss when following static-abstract pixel dispatch indirectly. + PixelOperations operations = PixelOperations.Instance; + + _ = operations.GetPixelTypeInfo(); + _ = operations.GetPixelBlender(default(GraphicsOptions)); + _ = operations.GetPixelBlender(default, default); + operations.FromVector4Destructive(default, default, default); + operations.FromVector4Destructive(default, default, default, default); + operations.ToVector4(default, default, default); + operations.ToVector4(default, default, default, default); + operations.PackFromRgbPlanes(default, default, default, default); + operations.UnpackIntoRgbPlanes(default, default, default, default); + + operations.FromArgb32Bytes(default, default, default, default); + operations.ToArgb32Bytes(default, default, default, default); + + operations.FromAbgr32Bytes(default, default, default, default); + operations.ToAbgr32Bytes(default, default, default, default); + + operations.FromBgr24Bytes(default, default, default, default); + operations.ToBgr24Bytes(default, default, default, default); + + operations.FromBgra32Bytes(default, default, default, default); + operations.ToBgra32Bytes(default, default, default, default); + + operations.FromL8Bytes(default, default, default, default); + operations.ToL8Bytes(default, default, default, default); + + operations.FromL16Bytes(default, default, default, default); + operations.ToL16Bytes(default, default, default, default); + + operations.FromLa16Bytes(default, default, default, default); + operations.ToLa16Bytes(default, default, default, default); + + operations.FromLa32Bytes(default, default, default, default); + operations.ToLa32Bytes(default, default, default, default); + + operations.FromRgb24Bytes(default, default, default, default); + operations.ToRgb24Bytes(default, default, default, default); + + operations.FromRgba32Bytes(default, default, default, default); + operations.ToRgba32Bytes(default, default, default, default); + + operations.FromRgb48Bytes(default, default, default, default); + operations.ToRgb48Bytes(default, default, default, default); + + operations.FromRgba64Bytes(default, default, default, default); + operations.ToRgba64Bytes(default, default, default, default); + + operations.FromBgra5551Bytes(default, default, default, default); + operations.ToBgra5551Bytes(default, default, default, default); + } + /// /// This method pre-seeds the for a given pixel format in the AoT compiler. /// @@ -229,8 +355,10 @@ internal static class AotCompilerTools where TPixel : unmanaged, IPixel { default(BmpEncoderCore).Encode(default, default, default); + default(CurEncoderCore).Encode(default, default, default); default(ExrEncoderCore).Encode(default, default, default); default(GifEncoderCore).Encode(default, default, default); + default(IcoEncoderCore).Encode(default, default, default); default(JpegEncoderCore).Encode(default, default, default); default(PbmEncoderCore).Encode(default, default, default); default(PngEncoderCore).Encode(default, default, default); @@ -249,8 +377,10 @@ internal static class AotCompilerTools where TPixel : unmanaged, IPixel { default(BmpDecoderCore).Decode(default, default, default); + default(CurDecoderCore).Decode(default, default, default); default(ExrDecoderCore).Decode(default, default, default); default(GifDecoderCore).Decode(default, default, default); + default(IcoDecoderCore).Decode(default, default, default); default(JpegDecoderCore).Decode(default, default, default); default(PbmDecoderCore).Decode(default, default, default); default(PngDecoderCore).Decode(default, default, default); @@ -270,11 +400,14 @@ internal static class AotCompilerTools { AotCompileImageEncoder(); AotCompileImageEncoder(); + AotCompileImageEncoder(); AotCompileImageEncoder(); AotCompileImageEncoder(); + AotCompileImageEncoder(); AotCompileImageEncoder(); AotCompileImageEncoder(); AotCompileImageEncoder(); + AotCompileImageEncoder(); AotCompileImageEncoder(); AotCompileImageEncoder(); } @@ -289,11 +422,14 @@ internal static class AotCompilerTools { AotCompileImageDecoder(); AotCompileImageDecoder(); + AotCompileImageDecoder(); AotCompileImageDecoder(); AotCompileImageDecoder(); + AotCompileImageDecoder(); AotCompileImageDecoder(); AotCompileImageDecoder(); AotCompileImageDecoder(); + AotCompileImageDecoder(); AotCompileImageDecoder(); AotCompileImageDecoder(); } diff --git a/src/ImageSharp/Configuration.cs b/src/ImageSharp/Configuration.cs index c09d78221..1e5433b9e 100644 --- a/src/ImageSharp/Configuration.cs +++ b/src/ImageSharp/Configuration.cs @@ -2,6 +2,8 @@ // Licensed under the Six Labors Split License. using System.Collections.Concurrent; +using System.Diagnostics.CodeAnalysis; +using SixLabors.ImageSharp.Advanced; using SixLabors.ImageSharp.Formats; using SixLabors.ImageSharp.Formats.Bmp; using SixLabors.ImageSharp.Formats.Cur; @@ -38,6 +40,9 @@ public sealed class Configuration /// /// Initializes a new instance of the class. /// + // Every image operation requires a Configuration. Attaching the dependency to its constructors keeps the compile-only + // seed graph visible to modern .NET trimmers without executing that graph or adding module-initialization work. + [DynamicDependency(nameof(AotCompilerTools.SeedPixelOperations), typeof(AotCompilerTools))] public Configuration() { } @@ -46,6 +51,8 @@ public sealed class Configuration /// Initializes a new instance of the class. /// /// A collection of configuration modules to register. + // The default Configuration is created through this overload, while callers may use either constructor. + [DynamicDependency(nameof(AotCompilerTools.SeedPixelOperations), typeof(AotCompilerTools))] public Configuration(params IImageFormatConfigurationModule[] configurationModules) { if (configurationModules != null)