diff --git a/src/ImageSharp/Image.WrapMemory.cs b/src/ImageSharp/Image.WrapMemory.cs index 778592931..383f64396 100644 --- a/src/ImageSharp/Image.WrapMemory.cs +++ b/src/ImageSharp/Image.WrapMemory.cs @@ -16,16 +16,22 @@ namespace SixLabors.ImageSharp public abstract partial class Image { /// - /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, - /// allowing to view/manipulate it as an instance. - /// The ownership of the underlying buffer for the input instance is not being transferred to - /// the new instance, meaning that consumers of this method need to make sure the input buffer - /// is either self-contianed (for instance, this is the case for a instance wrapping a new array that was - /// created), or that the owning object is not disposed until the returned is not disposed. - /// For instance, if the input instance is one retrieved from an instance + /// + /// Wraps an existing contiguous memory area of 'width' x 'height' pixels allowing viewing/manipulation as + /// an instance. + /// + /// + /// Please note: using this method does not transfer the ownership of the underlying buffer of the input + /// to the new instance. This means that consumers of this method must ensure that the input buffer + /// is either self-contained, (for example, a instance wrapping a new array that was + /// created), or that the owning object is not disposed until the returned is disposed. + /// + /// + /// If the input instance is one retrieved from an instance /// rented from a memory pool (such as ), and that owning instance is disposed while the image is still /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other - /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly. + /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers appropriately. + /// /// /// The pixel type /// The @@ -53,16 +59,22 @@ namespace SixLabors.ImageSharp } /// - /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, - /// allowing to view/manipulate it as an instance. - /// The ownership of the underlying buffer for the input instance is not being transferred to - /// the new instance, meaning that consumers of this method need to make sure the input buffer - /// is either self-contianed (for instance, this is the case for a instance wrapping a new array that was - /// created), or that the owning object is not disposed until the returned is not disposed. - /// For instance, if the input instance is one retrieved from an instance + /// + /// Wraps an existing contiguous memory area of 'width' x 'height' pixels allowing viewing/manipulation as + /// an instance. + /// + /// + /// Please note: using this method does not transfer the ownership of the underlying buffer of the input + /// to the new instance. This means that consumers of this method must ensure that the input buffer + /// is either self-contained, (for example, a instance wrapping a new array that was + /// created), or that the owning object is not disposed until the returned is disposed. + /// + /// + /// If the input instance is one retrieved from an instance /// rented from a memory pool (such as ), and that owning instance is disposed while the image is still /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other - /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly. + /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers appropriately. + /// /// /// The pixel type /// The @@ -80,16 +92,22 @@ namespace SixLabors.ImageSharp => WrapMemory(configuration, pixelMemory, width, height, new ImageMetadata()); /// - /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, - /// allowing to view/manipulate it as an instance. - /// The ownership of the underlying buffer for the input instance is not being transferred to - /// the new instance, meaning that consumers of this method need to make sure the input buffer - /// is either self-contianed (for instance, this is the case for a instance wrapping a new array that was - /// created), or that the owning object is not disposed until the returned is not disposed. - /// For instance, if the input instance is one retrieved from an instance + /// + /// Wraps an existing contiguous memory area of 'width' x 'height' pixels allowing viewing/manipulation as + /// an instance. + /// + /// + /// Please note: using this method does not transfer the ownership of the underlying buffer of the input + /// to the new instance. This means that consumers of this method must ensure that the input buffer + /// is either self-contained, (for example, a instance wrapping a new array that was + /// created), or that the owning object is not disposed until the returned is disposed. + /// + /// + /// If the input instance is one retrieved from an instance /// rented from a memory pool (such as ), and that owning instance is disposed while the image is still /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other - /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly. + /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers appropriately. + /// /// /// The pixel type. /// The pixel memory. @@ -177,16 +195,22 @@ namespace SixLabors.ImageSharp => WrapMemory(Configuration.Default, pixelMemoryOwner, width, height); /// - /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, - /// allowing to view/manipulate it as an instance. - /// The ownership of the underlying buffer for the input instance is not being transferred to - /// the new instance, meaning that consumers of this method need to make sure the input buffer - /// is either self-contianed (for instance, this is the case for a instance wrapping a new array that was - /// created), or that the owning object is not disposed until the returned is not disposed. - /// For instance, if the input instance is one retrieved from an instance + /// + /// Wraps an existing contiguous memory area of 'width' x 'height' pixels allowing viewing/manipulation as + /// an instance. + /// + /// + /// Please note: using this method does not transfer the ownership of the underlying buffer of the input + /// to the new instance. This means that consumers of this method must ensure that the input buffer + /// is either self-contained, (for example, a instance wrapping a new array that was + /// created), or that the owning object is not disposed until the returned is disposed. + /// + /// + /// If the input instance is one retrieved from an instance /// rented from a memory pool (such as ), and that owning instance is disposed while the image is still /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other - /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly. + /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers appropriately. + /// /// /// The pixel type /// The @@ -217,16 +241,22 @@ namespace SixLabors.ImageSharp } /// - /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, - /// allowing to view/manipulate it as an instance. - /// The ownership of the underlying buffer for the input instance is not being transferred to - /// the new instance, meaning that consumers of this method need to make sure the input buffer - /// is either self-contianed (for instance, this is the case for a instance wrapping a new array that was - /// created), or that the owning object is not disposed until the returned is not disposed. - /// For instance, if the input instance is one retrieved from an instance + /// + /// Wraps an existing contiguous memory area of 'width' x 'height' pixels allowing viewing/manipulation as + /// an instance. + /// + /// + /// Please note: using this method does not transfer the ownership of the underlying buffer of the input + /// to the new instance. This means that consumers of this method must ensure that the input buffer + /// is either self-contained, (for example, a instance wrapping a new array that was + /// created), or that the owning object is not disposed until the returned is disposed. + /// + /// + /// If the input instance is one retrieved from an instance /// rented from a memory pool (such as ), and that owning instance is disposed while the image is still /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other - /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly. + /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers appropriately. + /// /// /// The pixel type /// The @@ -244,16 +274,22 @@ namespace SixLabors.ImageSharp => WrapMemory(configuration, byteMemory, width, height, new ImageMetadata()); /// - /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, - /// allowing to view/manipulate it as an instance. - /// The ownership of the underlying buffer for the input instance is not being transferred to - /// the new instance, meaning that consumers of this method need to make sure the input buffer - /// is either self-contianed (for instance, this is the case for a instance wrapping a new array that was - /// created), or that the owning object is not disposed until the returned is not disposed. - /// For instance, if the input instance is one retrieved from an instance + /// + /// Wraps an existing contiguous memory area of 'width' x 'height' pixels allowing viewing/manipulation as + /// an instance. + /// + /// + /// Please note: using this method does not transfer the ownership of the underlying buffer of the input + /// to the new instance. This means that consumers of this method must ensure that the input buffer + /// is either self-contained, (for example, a instance wrapping a new array that was + /// created), or that the owning object is not disposed until the returned is disposed. + /// + /// + /// If the input instance is one retrieved from an instance /// rented from a memory pool (such as ), and that owning instance is disposed while the image is still /// in use, this will lead to undefined behavior and possibly runtime crashes (as the same buffer might then be modified by other - /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers properly. + /// consumers while the returned image is still working on it). Make sure to control the lifetime of the input buffers appropriately. + /// /// /// The pixel type. /// The byte memory representing the pixel data. @@ -268,21 +304,27 @@ namespace SixLabors.ImageSharp => WrapMemory(Configuration.Default, byteMemory, width, height); /// - /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, - /// allowing to view/manipulate it as an instance. - /// This method relies on callers to carefully manage the target memory area being referenced by the - /// pointer, and it requires that the lifetime of such a memory area is at least equal to that of the returned - /// instance. For instance, if the input pointer references an unmanaged memory area, - /// callers need to ensure that that memory area is not freed as long as the returned is + /// + /// Wraps an existing contiguous memory area of 'width' x 'height' pixels allowing viewing/manipulation as + /// an instance. + /// + /// + /// Please note: this method relies on callers to carefully manage the target memory area being referenced by the + /// pointer and that the lifetime of such a memory area is at least equal to that of the returned + /// instance. For example, if the input pointer references an unmanaged memory area, + /// callers must ensure that the memory area is not freed as long as the returned is /// in use and not disposed. The same applies if the input memory area points to a pinned managed object, as callers - /// need to ensure that object will remain pinned as long as the instance is in use. + /// must ensure that objects will remain pinned as long as the instance is in use. /// Failing to do so constitutes undefined behavior and will likely lead to memory corruption and runtime crashes. - /// Note that if you have a or an array (which can be cast to ) of + /// + /// + /// Note also that if you have a or an array (which can be cast to ) of /// either or values, it is highly recommended to use one of the other /// available overloads of this method instead (such as /// or , to make the resulting code less error /// prone and avoid having to pin the underlying memory buffer in use. This method is primarily meant to be used when /// doing interop or working with buffers that are located in unmanaged memory. + /// /// /// The pixel type /// The @@ -312,21 +354,27 @@ namespace SixLabors.ImageSharp } /// - /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, - /// allowing to view/manipulate it as an instance. - /// This method relies on callers to carefully manage the target memory area being referenced by the - /// pointer, and it requires that the lifetime of such a memory area is at least equal to that of the returned - /// instance. For instance, if the input pointer references an unmanaged memory area, - /// callers need to ensure that that memory area is not freed as long as the returned is + /// + /// Wraps an existing contiguous memory area of 'width' x 'height' pixels allowing viewing/manipulation as + /// an instance. + /// + /// + /// Please note: this method relies on callers to carefully manage the target memory area being referenced by the + /// pointer and that the lifetime of such a memory area is at least equal to that of the returned + /// instance. For example, if the input pointer references an unmanaged memory area, + /// callers must ensure that the memory area is not freed as long as the returned is /// in use and not disposed. The same applies if the input memory area points to a pinned managed object, as callers - /// need to ensure that object will remain pinned as long as the instance is in use. + /// must ensure that objects will remain pinned as long as the instance is in use. /// Failing to do so constitutes undefined behavior and will likely lead to memory corruption and runtime crashes. - /// Note that if you have a or an array (which can be cast to ) of + /// + /// + /// Note also that if you have a or an array (which can be cast to ) of /// either or values, it is highly recommended to use one of the other /// available overloads of this method instead (such as /// or , to make the resulting code less error /// prone and avoid having to pin the underlying memory buffer in use. This method is primarily meant to be used when /// doing interop or working with buffers that are located in unmanaged memory. + /// /// /// The pixel type /// The @@ -344,21 +392,27 @@ namespace SixLabors.ImageSharp => WrapMemory(configuration, pointer, width, height, new ImageMetadata()); /// - /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, - /// allowing to view/manipulate it as an instance. - /// This method relies on callers to carefully manage the target memory area being referenced by the - /// pointer, and it requires that the lifetime of such a memory area is at least equal to that of the returned - /// instance. For instance, if the input pointer references an unmanaged memory area, - /// callers need to ensure that that memory area is not freed as long as the returned is + /// + /// Wraps an existing contiguous memory area of 'width' x 'height' pixels allowing viewing/manipulation as + /// an instance. + /// + /// + /// Please note: this method relies on callers to carefully manage the target memory area being referenced by the + /// pointer and that the lifetime of such a memory area is at least equal to that of the returned + /// instance. For example, if the input pointer references an unmanaged memory area, + /// callers must ensure that the memory area is not freed as long as the returned is /// in use and not disposed. The same applies if the input memory area points to a pinned managed object, as callers - /// need to ensure that object will remain pinned as long as the instance is in use. + /// must ensure that objects will remain pinned as long as the instance is in use. /// Failing to do so constitutes undefined behavior and will likely lead to memory corruption and runtime crashes. - /// Note that if you have a or an array (which can be cast to ) of + /// + /// + /// Note also that if you have a or an array (which can be cast to ) of /// either or values, it is highly recommended to use one of the other /// available overloads of this method instead (such as /// or , to make the resulting code less error /// prone and avoid having to pin the underlying memory buffer in use. This method is primarily meant to be used when /// doing interop or working with buffers that are located in unmanaged memory. + /// /// /// The pixel type. /// The pointer to the target memory buffer to wrap.