Class-wide ownership means that an image is not owned only by a particular instance of ImageVariant, but by all existing instances that transport the same image.
In first place let's clarify the concept of image ownership in ImageVariant. Consider the following code snippets:
Image image;
ImageVariant var( &image );
// ImageVariant does not own image
ImageVariant var;
var.CreateFloatImage();
// ImageVariant owns a newly created image
In the first case, you have an image and create an ImageVariant to transport it. When the var object gets out of scope, image will continue existing and won't be destroyed.
In the second case, you have an ImageVariant and tell it to create a new image (a 32-bit floating point image in the example). The newly created image will be transported by var and is now owned by ImageVariant.
You can also switch on and off ImageVariant's ownership:
Image* image = new Image;
ImageVariant var( image );
var.SetOwnership( true );
// now ImageVariant owns image
(Of course, don't do that for images allocated in the stack as automatic variables, or your module will crash for sure).
Now let's put a few examples to describe class-wide ownership.
Console console;
ImageVariant var;
console << bool( var ) << '\n'; // writes 'false' to the console
{
ImageVariant tmp;
tmp.CreateFloatImage();
var = tmp;
}
console << bool( var ) << '\n'; // writes 'true' to the console
console << var.OwnsImage() << '\n'; // also writes 'true'
In this example I'm using "ImageVariant::operator bool() const" (PCL 2.0), which returns true if the ImageVariant transports an image. The tmp object creates a new image, which is owned by default. Then we force var to transport the same image. When tmp gets out of scope the image is not destroyed, since it is still being transported by one or more ImageVariant instances (var in this case). If instead of class-wide ownership we had instance ownership, the image would be destroyed by tmp at the end of the block, and var would be left in an invalid state.
You may argue that this is how implicit data sharing works, so there's nothing really special here. But note that ImageVariant implements an explicit data sharing mechanism, which makes it different from the rest of container classes in PCL. It is important to state clearly that ownership of image data is not a property of any particular object in this case, but of the whole ImageVariant class.
As you know PCL allows you to work transparently with two types of images: local and shared images. Local images allocate their data in the calling module's heap. Shared images live in the PixInsight Core application, and the client-side GenericImage objects are just managed aliases. Image ownership and the associated explicit data sharing mechanism in ImageVariant work equally for local and shared images. For shared images, however, ImageVariant's ownership extends beyond the calling module and includes also all ImageVariant instances in the core application. This is why you can access an image in a View object, and when your View instances are destroyed the corresponding (shared) images are not destroyed.
Hope this clarifies.
