Struct Image 

pub struct Image { /* private fields */ }

Safe owner for an Objective-C MPSImage.

Implementations

impl Image

pub fn new(device: &MetalDevice, descriptor: ImageDescriptor) -> Option<Self>

Allocate a lazily backed MPSImage on device.

Examples found in repository

examples/01_blur_image.rs (line 11)

fn main() {
    let device = MetalDevice::system_default().expect("no Metal device available");
    let queue = device
        .new_command_queue()
        .expect("failed to create command queue");

    let descriptor = ImageDescriptor::new(256, 256, 1, feature_channel_format::FLOAT32);
    let src = Image::new(&device, descriptor).expect("failed to allocate source image");
    let dst = Image::new(&device, descriptor).expect("failed to allocate destination image");

    let mut impulse = vec![0.0_f32; 256 * 256];
    let center_index = (256 / 2) * 256 + (256 / 2);
    impulse[center_index] = 1.0;
    src.write_f32(&impulse)
        .expect("failed to upload source image");

    let blur = ImageGaussianBlur::new(&device, 2.0).expect("failed to create gaussian blur");
    let command_buffer = queue
        .new_command_buffer()
        .expect("failed to allocate command buffer");
    blur.encode_image(&command_buffer, &src, &dst);
    command_buffer.commit();
    command_buffer.wait_until_completed();

    let output = dst.read_f32().expect("failed to download blurred image");
    let center_value = output[center_index];
    let neighbor_value = output[center_index + 1];
    let corner_value = output[0];
    let total_energy: f32 = output.iter().sum();

    assert!(
        center_value < 1.0,
        "center should have blurred away from impulse"
    );
    assert!(
        neighbor_value > 0.0,
        "neighbor should receive energy after blur"
    );
    assert!(
        center_value > neighbor_value,
        "center should remain strongest sample"
    );
    assert!(corner_value.abs() < 1.0e-6, "corners should stay at zero");
    assert!(
        (total_energy - 1.0).abs() < 1.0e-2,
        "gaussian blur should preserve energy, got {total_energy}"
    );

    println!(
        "blur smoke passed: center={center_value:.6} neighbor={neighbor_value:.6} sum={total_energy:.6}"
    );
}

pub fn from_texture( texture: &MetalTexture, feature_channels: usize, ) -> Option<Self>

Wrap an existing Metal texture in an MPSImage.

pub const fn as_ptr(&self) -> *mut c_void

Raw MPSImage pointer.

pub fn width(&self) -> usize

Image width in pixels.

pub fn height(&self) -> usize

Image height in pixels.

pub fn feature_channels(&self) -> usize

Number of feature channels per pixel.

pub fn number_of_images(&self) -> usize

Number of images stored in the backing texture array.

pub fn pixel_size(&self) -> usize

Bytes between neighboring pixels in storage order.

pub fn pixel_format(&self) -> usize

Underlying MTLPixelFormat raw value.

pub fn whole_region(&self) -> ImageRegion

Convenience region covering the full first image.

pub fn read_bytes( &self, dst: &mut [u8], data_layout: usize, bytes_per_row: usize, region: ImageRegion, params: ImageReadWriteParams, image_index: usize, ) -> Result<()>

Read bytes out of the image into a caller-provided buffer.

pub fn write_bytes( &self, src: &[u8], data_layout: usize, bytes_per_row: usize, region: ImageRegion, params: ImageReadWriteParams, image_index: usize, ) -> Result<()>

Write bytes into the image from a caller-provided buffer.

pub fn read_f32(&self) -> Result<Vec<f32>>

Read the first image slice as tightly packed float32 HWC data.

Examples found in repository

examples/01_blur_image.rs (line 28)

fn main() {
    let device = MetalDevice::system_default().expect("no Metal device available");
    let queue = device
        .new_command_queue()
        .expect("failed to create command queue");

    let descriptor = ImageDescriptor::new(256, 256, 1, feature_channel_format::FLOAT32);
    let src = Image::new(&device, descriptor).expect("failed to allocate source image");
    let dst = Image::new(&device, descriptor).expect("failed to allocate destination image");

    let mut impulse = vec![0.0_f32; 256 * 256];
    let center_index = (256 / 2) * 256 + (256 / 2);
    impulse[center_index] = 1.0;
    src.write_f32(&impulse)
        .expect("failed to upload source image");

    let blur = ImageGaussianBlur::new(&device, 2.0).expect("failed to create gaussian blur");
    let command_buffer = queue
        .new_command_buffer()
        .expect("failed to allocate command buffer");
    blur.encode_image(&command_buffer, &src, &dst);
    command_buffer.commit();
    command_buffer.wait_until_completed();

    let output = dst.read_f32().expect("failed to download blurred image");
    let center_value = output[center_index];
    let neighbor_value = output[center_index + 1];
    let corner_value = output[0];
    let total_energy: f32 = output.iter().sum();

    assert!(
        center_value < 1.0,
        "center should have blurred away from impulse"
    );
    assert!(
        neighbor_value > 0.0,
        "neighbor should receive energy after blur"
    );
    assert!(
        center_value > neighbor_value,
        "center should remain strongest sample"
    );
    assert!(corner_value.abs() < 1.0e-6, "corners should stay at zero");
    assert!(
        (total_energy - 1.0).abs() < 1.0e-2,
        "gaussian blur should preserve energy, got {total_energy}"
    );

    println!(
        "blur smoke passed: center={center_value:.6} neighbor={neighbor_value:.6} sum={total_energy:.6}"
    );
}

pub fn write_f32(&self, data: &[f32]) -> Result<()>

Write tightly packed float32 HWC data into the first image slice.

Examples found in repository

examples/01_blur_image.rs (line 17)

fn main() {
    let device = MetalDevice::system_default().expect("no Metal device available");
    let queue = device
        .new_command_queue()
        .expect("failed to create command queue");

    let descriptor = ImageDescriptor::new(256, 256, 1, feature_channel_format::FLOAT32);
    let src = Image::new(&device, descriptor).expect("failed to allocate source image");
    let dst = Image::new(&device, descriptor).expect("failed to allocate destination image");

    let mut impulse = vec![0.0_f32; 256 * 256];
    let center_index = (256 / 2) * 256 + (256 / 2);
    impulse[center_index] = 1.0;
    src.write_f32(&impulse)
        .expect("failed to upload source image");

    let blur = ImageGaussianBlur::new(&device, 2.0).expect("failed to create gaussian blur");
    let command_buffer = queue
        .new_command_buffer()
        .expect("failed to allocate command buffer");
    blur.encode_image(&command_buffer, &src, &dst);
    command_buffer.commit();
    command_buffer.wait_until_completed();

    let output = dst.read_f32().expect("failed to download blurred image");
    let center_value = output[center_index];
    let neighbor_value = output[center_index + 1];
    let corner_value = output[0];
    let total_energy: f32 = output.iter().sum();

    assert!(
        center_value < 1.0,
        "center should have blurred away from impulse"
    );
    assert!(
        neighbor_value > 0.0,
        "neighbor should receive energy after blur"
    );
    assert!(
        center_value > neighbor_value,
        "center should remain strongest sample"
    );
    assert!(corner_value.abs() < 1.0e-6, "corners should stay at zero");
    assert!(
        (total_energy - 1.0).abs() < 1.0e-2,
        "gaussian blur should preserve energy, got {total_energy}"
    );

    println!(
        "blur smoke passed: center={center_value:.6} neighbor={neighbor_value:.6} sum={total_energy:.6}"
    );
}

Trait Implementations

impl Drop for Image

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl Send for Image

impl Sync for Image