From 2c517a2fbcf2864c58ed36c33b22c5cda40bd7a5 Mon Sep 17 00:00:00 2001 From: winscripter <142818255+winscripter@users.noreply.github.com> Date: Sat, 8 Aug 2026 21:36:39 +0400 Subject: [PATCH] Document JxlPlane and JxlPlaneBase --- .../Formats/Jxl/Memory/JxlPlaneBase.cs | 75 ++++++++++++++++++- .../Formats/Jxl/Memory/JxlPlane{T}.cs | 45 ++++++++++- 2 files changed, 116 insertions(+), 4 deletions(-) diff --git a/src/ImageSharp/Formats/Jxl/Memory/JxlPlaneBase.cs b/src/ImageSharp/Formats/Jxl/Memory/JxlPlaneBase.cs index 367b3fc30..1b63eb43f 100644 --- a/src/ImageSharp/Formats/Jxl/Memory/JxlPlaneBase.cs +++ b/src/ImageSharp/Formats/Jxl/Memory/JxlPlaneBase.cs @@ -7,11 +7,22 @@ using System.Runtime.InteropServices; namespace SixLabors.ImageSharp.Formats.Jxl.Memory; -// NOTE: Do not seal this type. +/// +/// Base class for a single-plane image. +/// internal class JxlPlaneBase : IDisposable { + /// + /// Underlying bytes + /// private IMemoryOwner? bytes; + /// + /// Initializes a new instance of the class. + /// + /// Plane width + /// Plane height + /// The size of each pixel in bytes. public JxlPlaneBase(int xSize, int ySize, int sizeOfT) { this.XSize = xSize; @@ -22,17 +33,32 @@ internal class JxlPlaneBase : IDisposable this.Size = sizeOfT; } + /// + /// Initializes a new instance of the class with empty values. + /// public JxlPlaneBase() : this(0, 0, 0) { } + /// + /// Gets the number of bytes per row. + /// public int BytesPerRow { get; private set; } + /// + /// Gets the width of the image. + /// public int XSize { get; private set; } + /// + /// Gets the height of the image. + /// public int YSize { get; private set; } + /// + /// Gets the underlying bytes of this image as a Memory<T>. + /// public Memory Bytes => #if DEBUG this.bytes?.Memory ?? throw new InvalidOperationException("Bytes are missing"); @@ -40,14 +66,31 @@ internal class JxlPlaneBase : IDisposable return this.bytes!.Memory; #endif + /// + /// Gets the underlying bytes of this image as a Span<T>. + /// public Span BytesSpan => this.Bytes.Span; protected int Size { get; set; } + /// + /// Gets or sets the width that was initially assigned. For example, if the image gets shrinked, + /// the XSize YSize properties get changed while this property will stay same. + /// protected int OriginalXSize { get; set; } + /// + /// Gets or sets the height that was initially assigned. For example, if the image gets shrinked, + /// the XSize YSize properties get changed while this property will stay same. + /// protected int OriginalYSize { get; set; } + /// + /// Allocates the underlying memory for the plane. + /// + /// The configuration which has a memory allocator used to allocate memory. + /// Padding + /// Status of allocation. public bool Allocate(Configuration configuration, int prePadding) { if (this.bytes != null || this.BytesPerRow != 0) @@ -67,6 +110,21 @@ internal class JxlPlaneBase : IDisposable return true; } + /// + /// Shrinks the image so its width is equal to and its height is + /// equal to . + /// + /// The output width + /// The output height + /// Status of the shrinking operation. + /// + /// + /// This method can only shrink memory. It cannot expand it. + /// + /// + /// When shrinking, the underlying memory does not get resized. + /// + /// [MethodImpl(MethodImplOptions.AggressiveInlining)] public bool ShrinkTo(int x, int y) { @@ -84,6 +142,12 @@ internal class JxlPlaneBase : IDisposable return true; } + /// + /// Base function to return the span for a specified row as a generic <T>. + /// + /// The type of the row. + /// The index of the row to get the span for. + /// A span which covers the row memory. protected Span GetRowBase(int y) where T : unmanaged { @@ -93,8 +157,10 @@ internal class JxlPlaneBase : IDisposable return MemoryMarshal.Cast(row); } - protected void SetBytes(IMemoryOwner bytes) => this.bytes = bytes; - + /// + /// Swaps properties & data of this image with the specified image. + /// + /// The other image to swap with. public void Swap(JxlPlaneBase other) { (this.XSize, other.XSize) = (other.XSize, this.XSize); @@ -105,6 +171,9 @@ internal class JxlPlaneBase : IDisposable (this.bytes, other.bytes) = (other.bytes, this.bytes); } + /// + /// Releases all underlying memory used by this plane. + /// public void Dispose() { this.bytes?.Dispose(); diff --git a/src/ImageSharp/Formats/Jxl/Memory/JxlPlane{T}.cs b/src/ImageSharp/Formats/Jxl/Memory/JxlPlane{T}.cs index e61381b19..2d96ab636 100644 --- a/src/ImageSharp/Formats/Jxl/Memory/JxlPlane{T}.cs +++ b/src/ImageSharp/Formats/Jxl/Memory/JxlPlane{T}.cs @@ -5,21 +5,44 @@ using SixLabors.ImageSharp.Formats.Jxl.Processing; namespace SixLabors.ImageSharp.Formats.Jxl.Memory; -// NOTE: Do not seal this class. +/// +/// A generic version of a 2D single-plane JPEG XL image. +/// +/// The type of each pixel. internal class JxlPlane : JxlPlaneBase where T : unmanaged { + /// + /// Initializes a new instance of the class. + /// public JxlPlane() { } + /// + /// Initializes a new instance of the class with the specified width and height. + /// + /// Plane width. + /// Plane height public unsafe JxlPlane(int width, int height) : base(width, height, sizeof(T)) { } + /// + /// Gets the number of pixels per row. + /// public unsafe int PixelsPerRow => this.BytesPerRow / sizeof(T); + /// + /// Allocates a new plane. + /// + /// The configuration which contains a memory allocator. + /// Plane width + /// Plane height + /// Padding + /// A new allocated plane + /// Thrown when allocation fails. public static JxlPlane Create(Configuration configuration, int xSize, int ySize, int prePadding = 0) { JxlPlane plane = new(xSize, ySize); @@ -34,8 +57,19 @@ internal class JxlPlane : JxlPlaneBase return plane; } + /// + /// Returns a span for the specified row. + /// + /// The row index. + /// A span which covers memory for the specified row. public Span GetRow(int y) => this.GetRowBase(y); + /// + /// Returns a span for the specified row within the specified rectangle bounds. + /// + /// The bounds. + /// The row index. + /// A span which covers memory for the specified row with the rectangle offsets. public Span GetRow(Rectangle rectangle, int y) { DebugGuard.MustBeGreaterThanOrEqualTo(y + rectangle.Top, 0, nameof(y)); @@ -43,8 +77,17 @@ internal class JxlPlane : JxlPlaneBase return this.GetRow(y + rectangle.Top)[rectangle.Left..]; } + /// + /// Checks if the specified rectangle is within the bounds image. + /// + /// The input rectangle. + /// Boolean indicating whether the rectangle is inside. public bool IsRectangleInside(Rectangle rectangle) => rectangle.Contains(this.GetRectangle()); + /// + /// Returns the rectangle for this image bounds. + /// + /// A rectangle with x,y=0,0 width,height=XSize,YSize. public Rectangle GetRectangle() => new(0, 0, this.XSize, this.YSize); ///