diff --git a/src/ImageSharp/Image.WrapMemory.cs b/src/ImageSharp/Image.WrapMemory.cs index dff888c13..778592931 100644 --- a/src/ImageSharp/Image.WrapMemory.cs +++ b/src/ImageSharp/Image.WrapMemory.cs @@ -18,6 +18,14 @@ 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 + /// 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. /// /// The pixel type /// The @@ -47,6 +55,14 @@ 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 + /// 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. /// /// The pixel type /// The @@ -66,7 +82,14 @@ namespace SixLabors.ImageSharp /// /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, /// allowing to view/manipulate it as an instance. - /// The memory is being observed, the caller remains responsible for managing it's lifecycle. + /// 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 + /// 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. /// /// The pixel type. /// The pixel memory. @@ -156,6 +179,14 @@ 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 + /// 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. /// /// The pixel type /// The @@ -188,6 +219,14 @@ 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 + /// 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. /// /// The pixel type /// The @@ -207,7 +246,14 @@ namespace SixLabors.ImageSharp /// /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, /// allowing to view/manipulate it as an instance. - /// The memory is being observed, the caller remains responsible for managing it's lifecycle. + /// 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 + /// 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. /// /// The pixel type. /// The byte memory representing the pixel data. @@ -224,6 +270,19 @@ 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 + /// 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. + /// 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 + /// 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 @@ -255,6 +314,19 @@ 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 + /// 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. + /// 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 + /// 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 @@ -274,7 +346,19 @@ namespace SixLabors.ImageSharp /// /// Wraps an existing contiguous memory area of 'width' x 'height' pixels, /// allowing to view/manipulate it as an instance. - /// The memory is being observed, the caller remains responsible for managing it's lifecycle. + /// 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 + /// 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. + /// 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 + /// 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.