Function tryImportOwnedRaster

Imports one retained raster backed by one OwnedByteResource.

OwnedRasterImportResult tryImportOwnedRaster(T)(
  ref OwnedByteResource resource,
  scope const(PlaneByteLayout)[] planes,
  Region2D residentRegion,
  ref RasterLease!T lease
) @safe;

The function itself is @safe.

The unsafe ownership claim has already occurred when the external physical resource was wrapped in OwnedByteResource.

Ownership semantics:

PRE-COMMIT failure: resource remains armed; lease remains unchanged.

success

resource is disarmed; lease retains the physical resource.

POST-COMMIT failure: resource is disarmed; retained construction has released the physical resource exactly once; no new lease is published.

lease must be empty on entry.

Multiple PlaneByteLayout entries may describe multiple logical planes within the same physical allocation.

Example

Example importing one owned 2 x 2 ubyte raster. 

import core.stdc.stdlib : malloc;
import raster;

void* memory = malloc(4);
assert(memory !is null);
auto samples = (cast(ubyte*) memory)[0 .. 4];
samples[] = [1, 2, 3, 4];

OwnedByteResource resource;
assert(tryAdoptMallocResource(memory, 4, resource));

const PlaneByteLayout[1] planes = [PlaneByteLayout(0, 2, 1)];
RasterLease!ubyte lease;

const result = tryImportOwnedRaster!ubyte(
    resource,
    planes[],
    Region2D(0, 0, 2, 2),
    lease
);

assert(result.ok);
assert(result.resourceDisposition == OwnedRasterResourceDisposition.transferredToLease);
assert(!resource.ownsResource);

scope auto view = lease.view();
ubyte value;
assert(view.trySample(0, 1, 1, value));
assert(value == 4);