Struct BlitCommandEncoder 

pub struct BlitCommandEncoder { /* private fields */ }

Re-exports the Metal framework surface for this item. Apple’s id<MTLBlitCommandEncoder> — encodes buffer and texture copy work.

Implementations

impl BlitCommandEncoder

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

Borrowed raw native command-encoder pointer.

The pointer is valid only until this wrapper is dropped. Calling endEncoding through it bypasses lifecycle tracking.

pub fn end_encoding(self) -> Result<(), CommandBufferError>

Finish encoding. Dropping an active encoder performs this once automatically.

Examples found in repository

examples/05_render_and_explicit_encoders.rs (line 40)

fn main() {
    let device = MetalDevice::system_default().expect("Metal device available");
    println!(
        "device: {} (registry id {})",
        device.name(),
        device.registry_id()
    );

    let queue = device.new_command_queue().expect("command queue");
    let status_buffer = unsafe {
        queue
            .new_command_buffer_with_unretained_references()
            .expect("scratch command buffer")
    };
    println!("scratch command buffer status={}", status_buffer.status());

    let src = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("source buffer");
    let dst = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("destination buffer");
    let blit_cb = queue.new_command_buffer().expect("blit command buffer");
    let mut blit = blit_cb
        .new_blit_command_encoder()
        .expect("blit command encoder");
    blit.fill_buffer(&src, 0..64, b'Z').expect("fill source");
    blit.copy_buffer(&src, 0, &dst, 0, 64)
        .expect("copy buffers");
    blit.end_encoding().expect("end blit encoder");
    blit_cb.commit().expect("commit blit");
    blit_cb.wait_until_completed().expect("complete blit");
    let copied = {
        let mapping = unsafe { dst.map_read().expect("map destination") };
        let copied = mapping[..8].to_vec();
        drop(mapping);
        copied
    };
    println!("blit copied bytes: {copied:?}");

    let library = device
        .new_library_with_source(common::COMPUTE_SRC)
        .expect("compile compute library");
    let increment = library
        .new_function("increment")
        .expect("increment function");
    let pipeline = device
        .new_compute_pipeline_state(&increment)
        .expect("compute pipeline");

    let buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("compute buffer");
    common::write_u32_words(&buffer, &[10, 20, 30, 40]);
    let compute_cb = queue.new_command_buffer().expect("compute command buffer");
    let mut compute = compute_cb
        .new_compute_command_encoder()
        .expect("compute command encoder");
    compute
        .set_compute_pipeline_state(&pipeline)
        .expect("bind compute pipeline");
    compute
        .set_buffer(&buffer, 0, 0)
        .expect("bind compute buffer");
    compute
        .dispatch_threads((4, 1, 1), (1, 1, 1))
        .expect("dispatch compute");
    compute.end_encoding().expect("end compute encoder");
    compute_cb.commit().expect("commit compute");
    compute_cb.wait_until_completed().expect("complete compute");
    println!("compute output: {:?}", common::read_u32_words(&buffer, 4));

    let render_library = device
        .new_library_with_source(common::RENDER_SRC)
        .expect("compile render library");
    let vertex = render_library
        .new_function("fullscreen_vertex")
        .expect("vertex function");
    let fragment = render_library
        .new_function("solid_fragment")
        .expect("fragment function");
    let render_pipeline = device
        .new_render_pipeline_state(&vertex, &fragment, pixel_format::BGRA8UNORM, 1)
        .expect("render pipeline");
    println!("render pipeline label: {:?}", render_pipeline.label());

    let render_target = device
        .new_texture(common::shared_render_target(4, 4))
        .expect("render target");
    let vertex_buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("vertex buffer");
    let render_cb = queue.new_command_buffer().expect("render command buffer");
    let mut render = render_cb
        .new_render_command_encoder(
            &render_target,
            load_action::CLEAR,
            store_action::STORE,
            [0.0, 0.0, 0.0, 1.0],
        )
        .expect("render command encoder");
    render
        .set_render_pipeline_state(&render_pipeline)
        .expect("bind render pipeline");
    render
        .set_vertex_buffer(&vertex_buffer, 0, 0)
        .expect("bind vertex buffer");
    render
        .draw_primitives(primitive_type::TRIANGLE, 0, 3)
        .expect("draw triangle");
    render.end_encoding().expect("end render encoder");
    render_cb.commit().expect("commit render");
    render_cb.wait_until_completed().expect("complete render");

    let mut rendered = vec![0_u8; 4 * 4 * 4];
    unsafe {
        render_target
            .read_bytes_2d(&mut rendered, 16, (0, 0), (4, 4), 0)
            .expect("read render target");
    }
    println!("first rendered pixel: {:?}", &rendered[..4]);

    let shared_texture = device
        .new_texture(TextureDescriptor::new_2d(4, 4, pixel_format::BGRA8UNORM))
        .expect("shared texture");
    let upload = vec![0x22_u8; 4 * 4 * 4];
    unsafe {
        shared_texture
            .replace_region_2d(&upload, 16, (0, 0), (4, 4), 0)
            .expect("upload texture");
    }
    let mut download = vec![0_u8; upload.len()];
    unsafe {
        shared_texture
            .read_bytes_2d(&mut download, 16, (0, 0), (4, 4), 0)
            .expect("read texture");
    }
    let view = shared_texture
        .new_view(pixel_format::BGRA8UNORM)
        .expect("texture view");
    println!(
        "texture {}x{} usage={} storage_mode={} view_width={}",
        shared_texture.width(),
        shared_texture.height(),
        shared_texture.usage(),
        shared_texture.storage_mode(),
        view.width(),
    );
}

examples/07_advanced_objects.rs (line 70)

fn main() {
    let device = MetalDevice::system_default().expect("Metal device available");
    let queue = device.new_command_queue().expect("command queue");
    let counter_sets = device.counter_set_names();
    println!("counter sets: {counter_sets:?}");

    if let Some(event) = device.new_shared_event() {
        event.set_signaled_value(1);
        println!("event signaled value={}", event.signaled_value());
        let signal = queue
            .new_command_buffer()
            .expect("event signal command buffer");
        signal
            .encode_signal_event(&event, 2)
            .expect("encode event signal");
        signal.commit().expect("commit event signal");
        signal
            .wait_until_completed()
            .expect("complete event signal");
        println!(
            "event reached value 2: {}",
            event.wait_until_signaled_value(2, 1_000),
        );

        let wait = queue
            .new_command_buffer()
            .expect("event wait command buffer");
        wait.encode_wait_for_event(&event, 2)
            .expect("encode event wait");
        wait.commit().expect("commit event wait");
        wait.wait_until_completed().expect("complete event wait");
    }

    let fence_a = device.new_fence();
    let fence_b = device.new_fence();
    let sample_buffer = counter_sets.first().and_then(|name| {
        if device.supports_counter_sampling(counter_sampling_point::AT_BLIT_BOUNDARY) {
            device
                .new_counter_sample_buffer(name, 2, storage_mode::SHARED, Some("example-samples"))
                .ok()
        } else {
            None
        }
    });

    let src = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("source buffer");
    let dst = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("destination buffer");
    let blit = queue.new_command_buffer().expect("blit command buffer");
    let mut encoder = blit.new_blit_command_encoder().expect("blit encoder");
    encoder
        .fill_buffer(&src, 0..64, b'Q')
        .expect("fill source buffer");
    if let Some(fence) = fence_a.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end first blit encoder");
    blit.commit().expect("commit first blit");
    blit.wait_until_completed().expect("complete first blit");

    let blit = queue
        .new_command_buffer()
        .expect("second blit command buffer");
    let mut encoder = blit
        .new_blit_command_encoder()
        .expect("second blit encoder");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        encoder
            .sample_counters(sample_buffer, 0, false)
            .expect("sample counters");
    }
    encoder
        .copy_buffer(&src, 0, &dst, 0, 64)
        .expect("copy buffers");
    encoder.end_encoding().expect("end second blit encoder");
    blit.commit().expect("commit second blit");
    blit.wait_until_completed().expect("complete second blit");
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        println!(
            "resolved counter bytes={}",
            sample_buffer
                .resolve_range(0..1)
                .map_or(0, |bytes| bytes.len())
        );
    }

    let library = device
        .new_library_with_source(common::COMPUTE_SRC)
        .expect("compile compute library");
    let increment = library
        .new_function("increment")
        .expect("increment function");
    let pipeline = device
        .new_compute_pipeline_state(&increment)
        .expect("compute pipeline");
    let visible_table = pipeline.new_visible_function_table(1);
    let intersection_table = if device.supports_raytracing() {
        pipeline.new_intersection_function_table(1)
    } else {
        None
    };
    if let Some(table) = intersection_table.as_ref() {
        table.set_opaque_triangle_intersection_function(intersection_function_signature::NONE, 0);
    }
    let acceleration_structure = if device.supports_raytracing() {
        device.new_acceleration_structure_with_size(256)
    } else {
        None
    };

    let buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("compute buffer");
    common::write_u32_words(&buffer, &[1, 2, 3, 4]);
    let texture = device
        .new_texture(apple_metal::TextureDescriptor::new_2d(
            4,
            4,
            apple_metal::pixel_format::BGRA8UNORM,
        ))
        .expect("compute texture");
    let compute = queue.new_command_buffer().expect("compute command buffer");
    let mut encoder = compute
        .new_compute_command_encoder()
        .expect("compute command encoder");
    encoder
        .set_compute_pipeline_state(&pipeline)
        .expect("bind compute pipeline");
    encoder
        .set_buffer(&buffer, 0, 0)
        .expect("bind compute buffer");
    encoder
        .set_texture(&texture, 1)
        .expect("bind compute texture");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(table) = visible_table.as_ref() {
        encoder
            .set_visible_function_table(table, 2)
            .expect("bind visible function table");
    }
    if let Some(table) = intersection_table.as_ref() {
        encoder
            .set_intersection_function_table(table, 3)
            .expect("bind intersection function table");
    }
    if let Some(acceleration_structure) = acceleration_structure.as_ref() {
        encoder
            .set_acceleration_structure(acceleration_structure, 4)
            .expect("bind acceleration structure");
    }
    encoder
        .dispatch_threadgroups((1, 1, 1), (4, 1, 1))
        .expect("dispatch compute");
    if let Some(fence) = fence_b.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end compute encoder");
    compute.commit().expect("commit compute");
    compute.wait_until_completed().expect("complete compute");
    println!(
        "compute buffer after dispatch: {:?}",
        common::read_u32_words(&buffer, 4)
    );

    if let Some(indirect) = device.new_indirect_command_buffer(
        indirect_command_type::CONCURRENT_DISPATCH,
        1,
        0,
        0,
        4,
        resource_options::STORAGE_MODE_PRIVATE,
    ) {
        indirect.reset_range(0..1);
        println!("indirect command buffer size={}", indirect.size());
    }

    if let Some(heap) = device.new_heap(1 << 20, storage_mode::SHARED) {
        if let Ok(residency_set) = device.new_residency_set(Some("example-residency"), 4) {
            let heap_buffer = heap
                .new_buffer(256, resource_options::STORAGE_MODE_SHARED)
                .expect("heap buffer");
            residency_set.add_buffer(&heap_buffer);
            residency_set.add_heap(&heap);
            residency_set.commit();
            residency_set.request_residency();
            queue.add_residency_set(&residency_set);
            queue.remove_residency_set(&residency_set);
            residency_set.end_residency();
            residency_set.remove_all_allocations();
            residency_set.commit();
            println!(
                "residency allocation count={}",
                residency_set.allocation_count()
            );
        } else {
            println!("residency sets unavailable on this OS");
        }
    }

    if let Some(capture_manager) = CaptureManager::shared() {
        println!(
            "capture supported for developer tools={} active={}",
            capture_manager.supports_destination(capture_destination::DEVELOPER_TOOLS),
            capture_manager.is_capturing(),
        );
        if let Some(scope) = capture_manager.new_capture_scope_with_device(&device) {
            scope.begin();
            scope.end();
        }
        if let Some(scope) = capture_manager.new_capture_scope_with_command_queue(&queue) {
            scope.begin();
            scope.end();
        }
    }
}

impl BlitCommandEncoder

pub fn copy_buffer( &mut self, src: &MetalBuffer, src_offset: usize, dst: &MetalBuffer, dst_offset: usize, size: usize, ) -> Result<(), CommandBufferError>

Copy size bytes from src into dst.

Examples found in repository

examples/05_render_and_explicit_encoders.rs (line 38)

fn main() {
    let device = MetalDevice::system_default().expect("Metal device available");
    println!(
        "device: {} (registry id {})",
        device.name(),
        device.registry_id()
    );

    let queue = device.new_command_queue().expect("command queue");
    let status_buffer = unsafe {
        queue
            .new_command_buffer_with_unretained_references()
            .expect("scratch command buffer")
    };
    println!("scratch command buffer status={}", status_buffer.status());

    let src = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("source buffer");
    let dst = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("destination buffer");
    let blit_cb = queue.new_command_buffer().expect("blit command buffer");
    let mut blit = blit_cb
        .new_blit_command_encoder()
        .expect("blit command encoder");
    blit.fill_buffer(&src, 0..64, b'Z').expect("fill source");
    blit.copy_buffer(&src, 0, &dst, 0, 64)
        .expect("copy buffers");
    blit.end_encoding().expect("end blit encoder");
    blit_cb.commit().expect("commit blit");
    blit_cb.wait_until_completed().expect("complete blit");
    let copied = {
        let mapping = unsafe { dst.map_read().expect("map destination") };
        let copied = mapping[..8].to_vec();
        drop(mapping);
        copied
    };
    println!("blit copied bytes: {copied:?}");

    let library = device
        .new_library_with_source(common::COMPUTE_SRC)
        .expect("compile compute library");
    let increment = library
        .new_function("increment")
        .expect("increment function");
    let pipeline = device
        .new_compute_pipeline_state(&increment)
        .expect("compute pipeline");

    let buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("compute buffer");
    common::write_u32_words(&buffer, &[10, 20, 30, 40]);
    let compute_cb = queue.new_command_buffer().expect("compute command buffer");
    let mut compute = compute_cb
        .new_compute_command_encoder()
        .expect("compute command encoder");
    compute
        .set_compute_pipeline_state(&pipeline)
        .expect("bind compute pipeline");
    compute
        .set_buffer(&buffer, 0, 0)
        .expect("bind compute buffer");
    compute
        .dispatch_threads((4, 1, 1), (1, 1, 1))
        .expect("dispatch compute");
    compute.end_encoding().expect("end compute encoder");
    compute_cb.commit().expect("commit compute");
    compute_cb.wait_until_completed().expect("complete compute");
    println!("compute output: {:?}", common::read_u32_words(&buffer, 4));

    let render_library = device
        .new_library_with_source(common::RENDER_SRC)
        .expect("compile render library");
    let vertex = render_library
        .new_function("fullscreen_vertex")
        .expect("vertex function");
    let fragment = render_library
        .new_function("solid_fragment")
        .expect("fragment function");
    let render_pipeline = device
        .new_render_pipeline_state(&vertex, &fragment, pixel_format::BGRA8UNORM, 1)
        .expect("render pipeline");
    println!("render pipeline label: {:?}", render_pipeline.label());

    let render_target = device
        .new_texture(common::shared_render_target(4, 4))
        .expect("render target");
    let vertex_buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("vertex buffer");
    let render_cb = queue.new_command_buffer().expect("render command buffer");
    let mut render = render_cb
        .new_render_command_encoder(
            &render_target,
            load_action::CLEAR,
            store_action::STORE,
            [0.0, 0.0, 0.0, 1.0],
        )
        .expect("render command encoder");
    render
        .set_render_pipeline_state(&render_pipeline)
        .expect("bind render pipeline");
    render
        .set_vertex_buffer(&vertex_buffer, 0, 0)
        .expect("bind vertex buffer");
    render
        .draw_primitives(primitive_type::TRIANGLE, 0, 3)
        .expect("draw triangle");
    render.end_encoding().expect("end render encoder");
    render_cb.commit().expect("commit render");
    render_cb.wait_until_completed().expect("complete render");

    let mut rendered = vec![0_u8; 4 * 4 * 4];
    unsafe {
        render_target
            .read_bytes_2d(&mut rendered, 16, (0, 0), (4, 4), 0)
            .expect("read render target");
    }
    println!("first rendered pixel: {:?}", &rendered[..4]);

    let shared_texture = device
        .new_texture(TextureDescriptor::new_2d(4, 4, pixel_format::BGRA8UNORM))
        .expect("shared texture");
    let upload = vec![0x22_u8; 4 * 4 * 4];
    unsafe {
        shared_texture
            .replace_region_2d(&upload, 16, (0, 0), (4, 4), 0)
            .expect("upload texture");
    }
    let mut download = vec![0_u8; upload.len()];
    unsafe {
        shared_texture
            .read_bytes_2d(&mut download, 16, (0, 0), (4, 4), 0)
            .expect("read texture");
    }
    let view = shared_texture
        .new_view(pixel_format::BGRA8UNORM)
        .expect("texture view");
    println!(
        "texture {}x{} usage={} storage_mode={} view_width={}",
        shared_texture.width(),
        shared_texture.height(),
        shared_texture.usage(),
        shared_texture.storage_mode(),
        view.width(),
    );
}

examples/07_advanced_objects.rs (line 89)

fn main() {
    let device = MetalDevice::system_default().expect("Metal device available");
    let queue = device.new_command_queue().expect("command queue");
    let counter_sets = device.counter_set_names();
    println!("counter sets: {counter_sets:?}");

    if let Some(event) = device.new_shared_event() {
        event.set_signaled_value(1);
        println!("event signaled value={}", event.signaled_value());
        let signal = queue
            .new_command_buffer()
            .expect("event signal command buffer");
        signal
            .encode_signal_event(&event, 2)
            .expect("encode event signal");
        signal.commit().expect("commit event signal");
        signal
            .wait_until_completed()
            .expect("complete event signal");
        println!(
            "event reached value 2: {}",
            event.wait_until_signaled_value(2, 1_000),
        );

        let wait = queue
            .new_command_buffer()
            .expect("event wait command buffer");
        wait.encode_wait_for_event(&event, 2)
            .expect("encode event wait");
        wait.commit().expect("commit event wait");
        wait.wait_until_completed().expect("complete event wait");
    }

    let fence_a = device.new_fence();
    let fence_b = device.new_fence();
    let sample_buffer = counter_sets.first().and_then(|name| {
        if device.supports_counter_sampling(counter_sampling_point::AT_BLIT_BOUNDARY) {
            device
                .new_counter_sample_buffer(name, 2, storage_mode::SHARED, Some("example-samples"))
                .ok()
        } else {
            None
        }
    });

    let src = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("source buffer");
    let dst = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("destination buffer");
    let blit = queue.new_command_buffer().expect("blit command buffer");
    let mut encoder = blit.new_blit_command_encoder().expect("blit encoder");
    encoder
        .fill_buffer(&src, 0..64, b'Q')
        .expect("fill source buffer");
    if let Some(fence) = fence_a.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end first blit encoder");
    blit.commit().expect("commit first blit");
    blit.wait_until_completed().expect("complete first blit");

    let blit = queue
        .new_command_buffer()
        .expect("second blit command buffer");
    let mut encoder = blit
        .new_blit_command_encoder()
        .expect("second blit encoder");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        encoder
            .sample_counters(sample_buffer, 0, false)
            .expect("sample counters");
    }
    encoder
        .copy_buffer(&src, 0, &dst, 0, 64)
        .expect("copy buffers");
    encoder.end_encoding().expect("end second blit encoder");
    blit.commit().expect("commit second blit");
    blit.wait_until_completed().expect("complete second blit");
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        println!(
            "resolved counter bytes={}",
            sample_buffer
                .resolve_range(0..1)
                .map_or(0, |bytes| bytes.len())
        );
    }

    let library = device
        .new_library_with_source(common::COMPUTE_SRC)
        .expect("compile compute library");
    let increment = library
        .new_function("increment")
        .expect("increment function");
    let pipeline = device
        .new_compute_pipeline_state(&increment)
        .expect("compute pipeline");
    let visible_table = pipeline.new_visible_function_table(1);
    let intersection_table = if device.supports_raytracing() {
        pipeline.new_intersection_function_table(1)
    } else {
        None
    };
    if let Some(table) = intersection_table.as_ref() {
        table.set_opaque_triangle_intersection_function(intersection_function_signature::NONE, 0);
    }
    let acceleration_structure = if device.supports_raytracing() {
        device.new_acceleration_structure_with_size(256)
    } else {
        None
    };

    let buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("compute buffer");
    common::write_u32_words(&buffer, &[1, 2, 3, 4]);
    let texture = device
        .new_texture(apple_metal::TextureDescriptor::new_2d(
            4,
            4,
            apple_metal::pixel_format::BGRA8UNORM,
        ))
        .expect("compute texture");
    let compute = queue.new_command_buffer().expect("compute command buffer");
    let mut encoder = compute
        .new_compute_command_encoder()
        .expect("compute command encoder");
    encoder
        .set_compute_pipeline_state(&pipeline)
        .expect("bind compute pipeline");
    encoder
        .set_buffer(&buffer, 0, 0)
        .expect("bind compute buffer");
    encoder
        .set_texture(&texture, 1)
        .expect("bind compute texture");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(table) = visible_table.as_ref() {
        encoder
            .set_visible_function_table(table, 2)
            .expect("bind visible function table");
    }
    if let Some(table) = intersection_table.as_ref() {
        encoder
            .set_intersection_function_table(table, 3)
            .expect("bind intersection function table");
    }
    if let Some(acceleration_structure) = acceleration_structure.as_ref() {
        encoder
            .set_acceleration_structure(acceleration_structure, 4)
            .expect("bind acceleration structure");
    }
    encoder
        .dispatch_threadgroups((1, 1, 1), (4, 1, 1))
        .expect("dispatch compute");
    if let Some(fence) = fence_b.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end compute encoder");
    compute.commit().expect("commit compute");
    compute.wait_until_completed().expect("complete compute");
    println!(
        "compute buffer after dispatch: {:?}",
        common::read_u32_words(&buffer, 4)
    );

    if let Some(indirect) = device.new_indirect_command_buffer(
        indirect_command_type::CONCURRENT_DISPATCH,
        1,
        0,
        0,
        4,
        resource_options::STORAGE_MODE_PRIVATE,
    ) {
        indirect.reset_range(0..1);
        println!("indirect command buffer size={}", indirect.size());
    }

    if let Some(heap) = device.new_heap(1 << 20, storage_mode::SHARED) {
        if let Ok(residency_set) = device.new_residency_set(Some("example-residency"), 4) {
            let heap_buffer = heap
                .new_buffer(256, resource_options::STORAGE_MODE_SHARED)
                .expect("heap buffer");
            residency_set.add_buffer(&heap_buffer);
            residency_set.add_heap(&heap);
            residency_set.commit();
            residency_set.request_residency();
            queue.add_residency_set(&residency_set);
            queue.remove_residency_set(&residency_set);
            residency_set.end_residency();
            residency_set.remove_all_allocations();
            residency_set.commit();
            println!(
                "residency allocation count={}",
                residency_set.allocation_count()
            );
        } else {
            println!("residency sets unavailable on this OS");
        }
    }

    if let Some(capture_manager) = CaptureManager::shared() {
        println!(
            "capture supported for developer tools={} active={}",
            capture_manager.supports_destination(capture_destination::DEVELOPER_TOOLS),
            capture_manager.is_capturing(),
        );
        if let Some(scope) = capture_manager.new_capture_scope_with_device(&device) {
            scope.begin();
            scope.end();
        }
        if let Some(scope) = capture_manager.new_capture_scope_with_command_queue(&queue) {
            scope.begin();
            scope.end();
        }
    }
}

pub fn fill_buffer( &mut self, buffer: &MetalBuffer, range: Range<usize>, value: u8, ) -> Result<(), CommandBufferError>

Fill a byte range of buffer with value.

Examples found in repository

examples/05_render_and_explicit_encoders.rs (line 37)

fn main() {
    let device = MetalDevice::system_default().expect("Metal device available");
    println!(
        "device: {} (registry id {})",
        device.name(),
        device.registry_id()
    );

    let queue = device.new_command_queue().expect("command queue");
    let status_buffer = unsafe {
        queue
            .new_command_buffer_with_unretained_references()
            .expect("scratch command buffer")
    };
    println!("scratch command buffer status={}", status_buffer.status());

    let src = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("source buffer");
    let dst = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("destination buffer");
    let blit_cb = queue.new_command_buffer().expect("blit command buffer");
    let mut blit = blit_cb
        .new_blit_command_encoder()
        .expect("blit command encoder");
    blit.fill_buffer(&src, 0..64, b'Z').expect("fill source");
    blit.copy_buffer(&src, 0, &dst, 0, 64)
        .expect("copy buffers");
    blit.end_encoding().expect("end blit encoder");
    blit_cb.commit().expect("commit blit");
    blit_cb.wait_until_completed().expect("complete blit");
    let copied = {
        let mapping = unsafe { dst.map_read().expect("map destination") };
        let copied = mapping[..8].to_vec();
        drop(mapping);
        copied
    };
    println!("blit copied bytes: {copied:?}");

    let library = device
        .new_library_with_source(common::COMPUTE_SRC)
        .expect("compile compute library");
    let increment = library
        .new_function("increment")
        .expect("increment function");
    let pipeline = device
        .new_compute_pipeline_state(&increment)
        .expect("compute pipeline");

    let buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("compute buffer");
    common::write_u32_words(&buffer, &[10, 20, 30, 40]);
    let compute_cb = queue.new_command_buffer().expect("compute command buffer");
    let mut compute = compute_cb
        .new_compute_command_encoder()
        .expect("compute command encoder");
    compute
        .set_compute_pipeline_state(&pipeline)
        .expect("bind compute pipeline");
    compute
        .set_buffer(&buffer, 0, 0)
        .expect("bind compute buffer");
    compute
        .dispatch_threads((4, 1, 1), (1, 1, 1))
        .expect("dispatch compute");
    compute.end_encoding().expect("end compute encoder");
    compute_cb.commit().expect("commit compute");
    compute_cb.wait_until_completed().expect("complete compute");
    println!("compute output: {:?}", common::read_u32_words(&buffer, 4));

    let render_library = device
        .new_library_with_source(common::RENDER_SRC)
        .expect("compile render library");
    let vertex = render_library
        .new_function("fullscreen_vertex")
        .expect("vertex function");
    let fragment = render_library
        .new_function("solid_fragment")
        .expect("fragment function");
    let render_pipeline = device
        .new_render_pipeline_state(&vertex, &fragment, pixel_format::BGRA8UNORM, 1)
        .expect("render pipeline");
    println!("render pipeline label: {:?}", render_pipeline.label());

    let render_target = device
        .new_texture(common::shared_render_target(4, 4))
        .expect("render target");
    let vertex_buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("vertex buffer");
    let render_cb = queue.new_command_buffer().expect("render command buffer");
    let mut render = render_cb
        .new_render_command_encoder(
            &render_target,
            load_action::CLEAR,
            store_action::STORE,
            [0.0, 0.0, 0.0, 1.0],
        )
        .expect("render command encoder");
    render
        .set_render_pipeline_state(&render_pipeline)
        .expect("bind render pipeline");
    render
        .set_vertex_buffer(&vertex_buffer, 0, 0)
        .expect("bind vertex buffer");
    render
        .draw_primitives(primitive_type::TRIANGLE, 0, 3)
        .expect("draw triangle");
    render.end_encoding().expect("end render encoder");
    render_cb.commit().expect("commit render");
    render_cb.wait_until_completed().expect("complete render");

    let mut rendered = vec![0_u8; 4 * 4 * 4];
    unsafe {
        render_target
            .read_bytes_2d(&mut rendered, 16, (0, 0), (4, 4), 0)
            .expect("read render target");
    }
    println!("first rendered pixel: {:?}", &rendered[..4]);

    let shared_texture = device
        .new_texture(TextureDescriptor::new_2d(4, 4, pixel_format::BGRA8UNORM))
        .expect("shared texture");
    let upload = vec![0x22_u8; 4 * 4 * 4];
    unsafe {
        shared_texture
            .replace_region_2d(&upload, 16, (0, 0), (4, 4), 0)
            .expect("upload texture");
    }
    let mut download = vec![0_u8; upload.len()];
    unsafe {
        shared_texture
            .read_bytes_2d(&mut download, 16, (0, 0), (4, 4), 0)
            .expect("read texture");
    }
    let view = shared_texture
        .new_view(pixel_format::BGRA8UNORM)
        .expect("texture view");
    println!(
        "texture {}x{} usage={} storage_mode={} view_width={}",
        shared_texture.width(),
        shared_texture.height(),
        shared_texture.usage(),
        shared_texture.storage_mode(),
        view.width(),
    );
}

examples/07_advanced_objects.rs (line 65)

fn main() {
    let device = MetalDevice::system_default().expect("Metal device available");
    let queue = device.new_command_queue().expect("command queue");
    let counter_sets = device.counter_set_names();
    println!("counter sets: {counter_sets:?}");

    if let Some(event) = device.new_shared_event() {
        event.set_signaled_value(1);
        println!("event signaled value={}", event.signaled_value());
        let signal = queue
            .new_command_buffer()
            .expect("event signal command buffer");
        signal
            .encode_signal_event(&event, 2)
            .expect("encode event signal");
        signal.commit().expect("commit event signal");
        signal
            .wait_until_completed()
            .expect("complete event signal");
        println!(
            "event reached value 2: {}",
            event.wait_until_signaled_value(2, 1_000),
        );

        let wait = queue
            .new_command_buffer()
            .expect("event wait command buffer");
        wait.encode_wait_for_event(&event, 2)
            .expect("encode event wait");
        wait.commit().expect("commit event wait");
        wait.wait_until_completed().expect("complete event wait");
    }

    let fence_a = device.new_fence();
    let fence_b = device.new_fence();
    let sample_buffer = counter_sets.first().and_then(|name| {
        if device.supports_counter_sampling(counter_sampling_point::AT_BLIT_BOUNDARY) {
            device
                .new_counter_sample_buffer(name, 2, storage_mode::SHARED, Some("example-samples"))
                .ok()
        } else {
            None
        }
    });

    let src = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("source buffer");
    let dst = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("destination buffer");
    let blit = queue.new_command_buffer().expect("blit command buffer");
    let mut encoder = blit.new_blit_command_encoder().expect("blit encoder");
    encoder
        .fill_buffer(&src, 0..64, b'Q')
        .expect("fill source buffer");
    if let Some(fence) = fence_a.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end first blit encoder");
    blit.commit().expect("commit first blit");
    blit.wait_until_completed().expect("complete first blit");

    let blit = queue
        .new_command_buffer()
        .expect("second blit command buffer");
    let mut encoder = blit
        .new_blit_command_encoder()
        .expect("second blit encoder");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        encoder
            .sample_counters(sample_buffer, 0, false)
            .expect("sample counters");
    }
    encoder
        .copy_buffer(&src, 0, &dst, 0, 64)
        .expect("copy buffers");
    encoder.end_encoding().expect("end second blit encoder");
    blit.commit().expect("commit second blit");
    blit.wait_until_completed().expect("complete second blit");
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        println!(
            "resolved counter bytes={}",
            sample_buffer
                .resolve_range(0..1)
                .map_or(0, |bytes| bytes.len())
        );
    }

    let library = device
        .new_library_with_source(common::COMPUTE_SRC)
        .expect("compile compute library");
    let increment = library
        .new_function("increment")
        .expect("increment function");
    let pipeline = device
        .new_compute_pipeline_state(&increment)
        .expect("compute pipeline");
    let visible_table = pipeline.new_visible_function_table(1);
    let intersection_table = if device.supports_raytracing() {
        pipeline.new_intersection_function_table(1)
    } else {
        None
    };
    if let Some(table) = intersection_table.as_ref() {
        table.set_opaque_triangle_intersection_function(intersection_function_signature::NONE, 0);
    }
    let acceleration_structure = if device.supports_raytracing() {
        device.new_acceleration_structure_with_size(256)
    } else {
        None
    };

    let buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("compute buffer");
    common::write_u32_words(&buffer, &[1, 2, 3, 4]);
    let texture = device
        .new_texture(apple_metal::TextureDescriptor::new_2d(
            4,
            4,
            apple_metal::pixel_format::BGRA8UNORM,
        ))
        .expect("compute texture");
    let compute = queue.new_command_buffer().expect("compute command buffer");
    let mut encoder = compute
        .new_compute_command_encoder()
        .expect("compute command encoder");
    encoder
        .set_compute_pipeline_state(&pipeline)
        .expect("bind compute pipeline");
    encoder
        .set_buffer(&buffer, 0, 0)
        .expect("bind compute buffer");
    encoder
        .set_texture(&texture, 1)
        .expect("bind compute texture");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(table) = visible_table.as_ref() {
        encoder
            .set_visible_function_table(table, 2)
            .expect("bind visible function table");
    }
    if let Some(table) = intersection_table.as_ref() {
        encoder
            .set_intersection_function_table(table, 3)
            .expect("bind intersection function table");
    }
    if let Some(acceleration_structure) = acceleration_structure.as_ref() {
        encoder
            .set_acceleration_structure(acceleration_structure, 4)
            .expect("bind acceleration structure");
    }
    encoder
        .dispatch_threadgroups((1, 1, 1), (4, 1, 1))
        .expect("dispatch compute");
    if let Some(fence) = fence_b.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end compute encoder");
    compute.commit().expect("commit compute");
    compute.wait_until_completed().expect("complete compute");
    println!(
        "compute buffer after dispatch: {:?}",
        common::read_u32_words(&buffer, 4)
    );

    if let Some(indirect) = device.new_indirect_command_buffer(
        indirect_command_type::CONCURRENT_DISPATCH,
        1,
        0,
        0,
        4,
        resource_options::STORAGE_MODE_PRIVATE,
    ) {
        indirect.reset_range(0..1);
        println!("indirect command buffer size={}", indirect.size());
    }

    if let Some(heap) = device.new_heap(1 << 20, storage_mode::SHARED) {
        if let Ok(residency_set) = device.new_residency_set(Some("example-residency"), 4) {
            let heap_buffer = heap
                .new_buffer(256, resource_options::STORAGE_MODE_SHARED)
                .expect("heap buffer");
            residency_set.add_buffer(&heap_buffer);
            residency_set.add_heap(&heap);
            residency_set.commit();
            residency_set.request_residency();
            queue.add_residency_set(&residency_set);
            queue.remove_residency_set(&residency_set);
            residency_set.end_residency();
            residency_set.remove_all_allocations();
            residency_set.commit();
            println!(
                "residency allocation count={}",
                residency_set.allocation_count()
            );
        } else {
            println!("residency sets unavailable on this OS");
        }
    }

    if let Some(capture_manager) = CaptureManager::shared() {
        println!(
            "capture supported for developer tools={} active={}",
            capture_manager.supports_destination(capture_destination::DEVELOPER_TOOLS),
            capture_manager.is_capturing(),
        );
        if let Some(scope) = capture_manager.new_capture_scope_with_device(&device) {
            scope.begin();
            scope.end();
        }
        if let Some(scope) = capture_manager.new_capture_scope_with_command_queue(&queue) {
            scope.begin();
            scope.end();
        }
    }
}

pub fn sample_counters( &mut self, sample_buffer: &CounterSampleBuffer, sample_index: usize, barrier: bool, ) -> Result<(), CommandBufferError>

Sample hardware counters into sample_buffer.

Examples found in repository

examples/07_advanced_objects.rs (line 85)

fn main() {
    let device = MetalDevice::system_default().expect("Metal device available");
    let queue = device.new_command_queue().expect("command queue");
    let counter_sets = device.counter_set_names();
    println!("counter sets: {counter_sets:?}");

    if let Some(event) = device.new_shared_event() {
        event.set_signaled_value(1);
        println!("event signaled value={}", event.signaled_value());
        let signal = queue
            .new_command_buffer()
            .expect("event signal command buffer");
        signal
            .encode_signal_event(&event, 2)
            .expect("encode event signal");
        signal.commit().expect("commit event signal");
        signal
            .wait_until_completed()
            .expect("complete event signal");
        println!(
            "event reached value 2: {}",
            event.wait_until_signaled_value(2, 1_000),
        );

        let wait = queue
            .new_command_buffer()
            .expect("event wait command buffer");
        wait.encode_wait_for_event(&event, 2)
            .expect("encode event wait");
        wait.commit().expect("commit event wait");
        wait.wait_until_completed().expect("complete event wait");
    }

    let fence_a = device.new_fence();
    let fence_b = device.new_fence();
    let sample_buffer = counter_sets.first().and_then(|name| {
        if device.supports_counter_sampling(counter_sampling_point::AT_BLIT_BOUNDARY) {
            device
                .new_counter_sample_buffer(name, 2, storage_mode::SHARED, Some("example-samples"))
                .ok()
        } else {
            None
        }
    });

    let src = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("source buffer");
    let dst = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("destination buffer");
    let blit = queue.new_command_buffer().expect("blit command buffer");
    let mut encoder = blit.new_blit_command_encoder().expect("blit encoder");
    encoder
        .fill_buffer(&src, 0..64, b'Q')
        .expect("fill source buffer");
    if let Some(fence) = fence_a.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end first blit encoder");
    blit.commit().expect("commit first blit");
    blit.wait_until_completed().expect("complete first blit");

    let blit = queue
        .new_command_buffer()
        .expect("second blit command buffer");
    let mut encoder = blit
        .new_blit_command_encoder()
        .expect("second blit encoder");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        encoder
            .sample_counters(sample_buffer, 0, false)
            .expect("sample counters");
    }
    encoder
        .copy_buffer(&src, 0, &dst, 0, 64)
        .expect("copy buffers");
    encoder.end_encoding().expect("end second blit encoder");
    blit.commit().expect("commit second blit");
    blit.wait_until_completed().expect("complete second blit");
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        println!(
            "resolved counter bytes={}",
            sample_buffer
                .resolve_range(0..1)
                .map_or(0, |bytes| bytes.len())
        );
    }

    let library = device
        .new_library_with_source(common::COMPUTE_SRC)
        .expect("compile compute library");
    let increment = library
        .new_function("increment")
        .expect("increment function");
    let pipeline = device
        .new_compute_pipeline_state(&increment)
        .expect("compute pipeline");
    let visible_table = pipeline.new_visible_function_table(1);
    let intersection_table = if device.supports_raytracing() {
        pipeline.new_intersection_function_table(1)
    } else {
        None
    };
    if let Some(table) = intersection_table.as_ref() {
        table.set_opaque_triangle_intersection_function(intersection_function_signature::NONE, 0);
    }
    let acceleration_structure = if device.supports_raytracing() {
        device.new_acceleration_structure_with_size(256)
    } else {
        None
    };

    let buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("compute buffer");
    common::write_u32_words(&buffer, &[1, 2, 3, 4]);
    let texture = device
        .new_texture(apple_metal::TextureDescriptor::new_2d(
            4,
            4,
            apple_metal::pixel_format::BGRA8UNORM,
        ))
        .expect("compute texture");
    let compute = queue.new_command_buffer().expect("compute command buffer");
    let mut encoder = compute
        .new_compute_command_encoder()
        .expect("compute command encoder");
    encoder
        .set_compute_pipeline_state(&pipeline)
        .expect("bind compute pipeline");
    encoder
        .set_buffer(&buffer, 0, 0)
        .expect("bind compute buffer");
    encoder
        .set_texture(&texture, 1)
        .expect("bind compute texture");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(table) = visible_table.as_ref() {
        encoder
            .set_visible_function_table(table, 2)
            .expect("bind visible function table");
    }
    if let Some(table) = intersection_table.as_ref() {
        encoder
            .set_intersection_function_table(table, 3)
            .expect("bind intersection function table");
    }
    if let Some(acceleration_structure) = acceleration_structure.as_ref() {
        encoder
            .set_acceleration_structure(acceleration_structure, 4)
            .expect("bind acceleration structure");
    }
    encoder
        .dispatch_threadgroups((1, 1, 1), (4, 1, 1))
        .expect("dispatch compute");
    if let Some(fence) = fence_b.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end compute encoder");
    compute.commit().expect("commit compute");
    compute.wait_until_completed().expect("complete compute");
    println!(
        "compute buffer after dispatch: {:?}",
        common::read_u32_words(&buffer, 4)
    );

    if let Some(indirect) = device.new_indirect_command_buffer(
        indirect_command_type::CONCURRENT_DISPATCH,
        1,
        0,
        0,
        4,
        resource_options::STORAGE_MODE_PRIVATE,
    ) {
        indirect.reset_range(0..1);
        println!("indirect command buffer size={}", indirect.size());
    }

    if let Some(heap) = device.new_heap(1 << 20, storage_mode::SHARED) {
        if let Ok(residency_set) = device.new_residency_set(Some("example-residency"), 4) {
            let heap_buffer = heap
                .new_buffer(256, resource_options::STORAGE_MODE_SHARED)
                .expect("heap buffer");
            residency_set.add_buffer(&heap_buffer);
            residency_set.add_heap(&heap);
            residency_set.commit();
            residency_set.request_residency();
            queue.add_residency_set(&residency_set);
            queue.remove_residency_set(&residency_set);
            residency_set.end_residency();
            residency_set.remove_all_allocations();
            residency_set.commit();
            println!(
                "residency allocation count={}",
                residency_set.allocation_count()
            );
        } else {
            println!("residency sets unavailable on this OS");
        }
    }

    if let Some(capture_manager) = CaptureManager::shared() {
        println!(
            "capture supported for developer tools={} active={}",
            capture_manager.supports_destination(capture_destination::DEVELOPER_TOOLS),
            capture_manager.is_capturing(),
        );
        if let Some(scope) = capture_manager.new_capture_scope_with_device(&device) {
            scope.begin();
            scope.end();
        }
        if let Some(scope) = capture_manager.new_capture_scope_with_command_queue(&queue) {
            scope.begin();
            scope.end();
        }
    }
}

pub fn synchronize_resource( &mut self, buffer: &MetalBuffer, ) -> Result<(), CommandBufferError>

Make managed resource writes visible to the CPU after completion.

pub fn synchronize_texture( &mut self, texture: &MetalTexture, ) -> Result<(), CommandBufferError>

Make managed texture writes visible to the CPU after completion.

pub fn update_fence(&mut self, fence: &Fence) -> Result<(), CommandBufferError>

Update fence with work encoded so far.

Examples found in repository

examples/07_advanced_objects.rs (line 68)

fn main() {
    let device = MetalDevice::system_default().expect("Metal device available");
    let queue = device.new_command_queue().expect("command queue");
    let counter_sets = device.counter_set_names();
    println!("counter sets: {counter_sets:?}");

    if let Some(event) = device.new_shared_event() {
        event.set_signaled_value(1);
        println!("event signaled value={}", event.signaled_value());
        let signal = queue
            .new_command_buffer()
            .expect("event signal command buffer");
        signal
            .encode_signal_event(&event, 2)
            .expect("encode event signal");
        signal.commit().expect("commit event signal");
        signal
            .wait_until_completed()
            .expect("complete event signal");
        println!(
            "event reached value 2: {}",
            event.wait_until_signaled_value(2, 1_000),
        );

        let wait = queue
            .new_command_buffer()
            .expect("event wait command buffer");
        wait.encode_wait_for_event(&event, 2)
            .expect("encode event wait");
        wait.commit().expect("commit event wait");
        wait.wait_until_completed().expect("complete event wait");
    }

    let fence_a = device.new_fence();
    let fence_b = device.new_fence();
    let sample_buffer = counter_sets.first().and_then(|name| {
        if device.supports_counter_sampling(counter_sampling_point::AT_BLIT_BOUNDARY) {
            device
                .new_counter_sample_buffer(name, 2, storage_mode::SHARED, Some("example-samples"))
                .ok()
        } else {
            None
        }
    });

    let src = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("source buffer");
    let dst = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("destination buffer");
    let blit = queue.new_command_buffer().expect("blit command buffer");
    let mut encoder = blit.new_blit_command_encoder().expect("blit encoder");
    encoder
        .fill_buffer(&src, 0..64, b'Q')
        .expect("fill source buffer");
    if let Some(fence) = fence_a.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end first blit encoder");
    blit.commit().expect("commit first blit");
    blit.wait_until_completed().expect("complete first blit");

    let blit = queue
        .new_command_buffer()
        .expect("second blit command buffer");
    let mut encoder = blit
        .new_blit_command_encoder()
        .expect("second blit encoder");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        encoder
            .sample_counters(sample_buffer, 0, false)
            .expect("sample counters");
    }
    encoder
        .copy_buffer(&src, 0, &dst, 0, 64)
        .expect("copy buffers");
    encoder.end_encoding().expect("end second blit encoder");
    blit.commit().expect("commit second blit");
    blit.wait_until_completed().expect("complete second blit");
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        println!(
            "resolved counter bytes={}",
            sample_buffer
                .resolve_range(0..1)
                .map_or(0, |bytes| bytes.len())
        );
    }

    let library = device
        .new_library_with_source(common::COMPUTE_SRC)
        .expect("compile compute library");
    let increment = library
        .new_function("increment")
        .expect("increment function");
    let pipeline = device
        .new_compute_pipeline_state(&increment)
        .expect("compute pipeline");
    let visible_table = pipeline.new_visible_function_table(1);
    let intersection_table = if device.supports_raytracing() {
        pipeline.new_intersection_function_table(1)
    } else {
        None
    };
    if let Some(table) = intersection_table.as_ref() {
        table.set_opaque_triangle_intersection_function(intersection_function_signature::NONE, 0);
    }
    let acceleration_structure = if device.supports_raytracing() {
        device.new_acceleration_structure_with_size(256)
    } else {
        None
    };

    let buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("compute buffer");
    common::write_u32_words(&buffer, &[1, 2, 3, 4]);
    let texture = device
        .new_texture(apple_metal::TextureDescriptor::new_2d(
            4,
            4,
            apple_metal::pixel_format::BGRA8UNORM,
        ))
        .expect("compute texture");
    let compute = queue.new_command_buffer().expect("compute command buffer");
    let mut encoder = compute
        .new_compute_command_encoder()
        .expect("compute command encoder");
    encoder
        .set_compute_pipeline_state(&pipeline)
        .expect("bind compute pipeline");
    encoder
        .set_buffer(&buffer, 0, 0)
        .expect("bind compute buffer");
    encoder
        .set_texture(&texture, 1)
        .expect("bind compute texture");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(table) = visible_table.as_ref() {
        encoder
            .set_visible_function_table(table, 2)
            .expect("bind visible function table");
    }
    if let Some(table) = intersection_table.as_ref() {
        encoder
            .set_intersection_function_table(table, 3)
            .expect("bind intersection function table");
    }
    if let Some(acceleration_structure) = acceleration_structure.as_ref() {
        encoder
            .set_acceleration_structure(acceleration_structure, 4)
            .expect("bind acceleration structure");
    }
    encoder
        .dispatch_threadgroups((1, 1, 1), (4, 1, 1))
        .expect("dispatch compute");
    if let Some(fence) = fence_b.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end compute encoder");
    compute.commit().expect("commit compute");
    compute.wait_until_completed().expect("complete compute");
    println!(
        "compute buffer after dispatch: {:?}",
        common::read_u32_words(&buffer, 4)
    );

    if let Some(indirect) = device.new_indirect_command_buffer(
        indirect_command_type::CONCURRENT_DISPATCH,
        1,
        0,
        0,
        4,
        resource_options::STORAGE_MODE_PRIVATE,
    ) {
        indirect.reset_range(0..1);
        println!("indirect command buffer size={}", indirect.size());
    }

    if let Some(heap) = device.new_heap(1 << 20, storage_mode::SHARED) {
        if let Ok(residency_set) = device.new_residency_set(Some("example-residency"), 4) {
            let heap_buffer = heap
                .new_buffer(256, resource_options::STORAGE_MODE_SHARED)
                .expect("heap buffer");
            residency_set.add_buffer(&heap_buffer);
            residency_set.add_heap(&heap);
            residency_set.commit();
            residency_set.request_residency();
            queue.add_residency_set(&residency_set);
            queue.remove_residency_set(&residency_set);
            residency_set.end_residency();
            residency_set.remove_all_allocations();
            residency_set.commit();
            println!(
                "residency allocation count={}",
                residency_set.allocation_count()
            );
        } else {
            println!("residency sets unavailable on this OS");
        }
    }

    if let Some(capture_manager) = CaptureManager::shared() {
        println!(
            "capture supported for developer tools={} active={}",
            capture_manager.supports_destination(capture_destination::DEVELOPER_TOOLS),
            capture_manager.is_capturing(),
        );
        if let Some(scope) = capture_manager.new_capture_scope_with_device(&device) {
            scope.begin();
            scope.end();
        }
        if let Some(scope) = capture_manager.new_capture_scope_with_command_queue(&queue) {
            scope.begin();
            scope.end();
        }
    }
}

pub fn wait_for_fence( &mut self, fence: &Fence, ) -> Result<(), CommandBufferError>

Wait for fence before executing subsequent work.

Examples found in repository

examples/07_advanced_objects.rs (line 81)

fn main() {
    let device = MetalDevice::system_default().expect("Metal device available");
    let queue = device.new_command_queue().expect("command queue");
    let counter_sets = device.counter_set_names();
    println!("counter sets: {counter_sets:?}");

    if let Some(event) = device.new_shared_event() {
        event.set_signaled_value(1);
        println!("event signaled value={}", event.signaled_value());
        let signal = queue
            .new_command_buffer()
            .expect("event signal command buffer");
        signal
            .encode_signal_event(&event, 2)
            .expect("encode event signal");
        signal.commit().expect("commit event signal");
        signal
            .wait_until_completed()
            .expect("complete event signal");
        println!(
            "event reached value 2: {}",
            event.wait_until_signaled_value(2, 1_000),
        );

        let wait = queue
            .new_command_buffer()
            .expect("event wait command buffer");
        wait.encode_wait_for_event(&event, 2)
            .expect("encode event wait");
        wait.commit().expect("commit event wait");
        wait.wait_until_completed().expect("complete event wait");
    }

    let fence_a = device.new_fence();
    let fence_b = device.new_fence();
    let sample_buffer = counter_sets.first().and_then(|name| {
        if device.supports_counter_sampling(counter_sampling_point::AT_BLIT_BOUNDARY) {
            device
                .new_counter_sample_buffer(name, 2, storage_mode::SHARED, Some("example-samples"))
                .ok()
        } else {
            None
        }
    });

    let src = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("source buffer");
    let dst = device
        .new_buffer(64, resource_options::STORAGE_MODE_SHARED)
        .expect("destination buffer");
    let blit = queue.new_command_buffer().expect("blit command buffer");
    let mut encoder = blit.new_blit_command_encoder().expect("blit encoder");
    encoder
        .fill_buffer(&src, 0..64, b'Q')
        .expect("fill source buffer");
    if let Some(fence) = fence_a.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end first blit encoder");
    blit.commit().expect("commit first blit");
    blit.wait_until_completed().expect("complete first blit");

    let blit = queue
        .new_command_buffer()
        .expect("second blit command buffer");
    let mut encoder = blit
        .new_blit_command_encoder()
        .expect("second blit encoder");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        encoder
            .sample_counters(sample_buffer, 0, false)
            .expect("sample counters");
    }
    encoder
        .copy_buffer(&src, 0, &dst, 0, 64)
        .expect("copy buffers");
    encoder.end_encoding().expect("end second blit encoder");
    blit.commit().expect("commit second blit");
    blit.wait_until_completed().expect("complete second blit");
    if let Some(sample_buffer) = sample_buffer.as_ref() {
        println!(
            "resolved counter bytes={}",
            sample_buffer
                .resolve_range(0..1)
                .map_or(0, |bytes| bytes.len())
        );
    }

    let library = device
        .new_library_with_source(common::COMPUTE_SRC)
        .expect("compile compute library");
    let increment = library
        .new_function("increment")
        .expect("increment function");
    let pipeline = device
        .new_compute_pipeline_state(&increment)
        .expect("compute pipeline");
    let visible_table = pipeline.new_visible_function_table(1);
    let intersection_table = if device.supports_raytracing() {
        pipeline.new_intersection_function_table(1)
    } else {
        None
    };
    if let Some(table) = intersection_table.as_ref() {
        table.set_opaque_triangle_intersection_function(intersection_function_signature::NONE, 0);
    }
    let acceleration_structure = if device.supports_raytracing() {
        device.new_acceleration_structure_with_size(256)
    } else {
        None
    };

    let buffer = device
        .new_buffer(16, resource_options::STORAGE_MODE_SHARED)
        .expect("compute buffer");
    common::write_u32_words(&buffer, &[1, 2, 3, 4]);
    let texture = device
        .new_texture(apple_metal::TextureDescriptor::new_2d(
            4,
            4,
            apple_metal::pixel_format::BGRA8UNORM,
        ))
        .expect("compute texture");
    let compute = queue.new_command_buffer().expect("compute command buffer");
    let mut encoder = compute
        .new_compute_command_encoder()
        .expect("compute command encoder");
    encoder
        .set_compute_pipeline_state(&pipeline)
        .expect("bind compute pipeline");
    encoder
        .set_buffer(&buffer, 0, 0)
        .expect("bind compute buffer");
    encoder
        .set_texture(&texture, 1)
        .expect("bind compute texture");
    if let Some(fence) = fence_a.as_ref() {
        encoder.wait_for_fence(fence).expect("wait for fence");
    }
    if let Some(table) = visible_table.as_ref() {
        encoder
            .set_visible_function_table(table, 2)
            .expect("bind visible function table");
    }
    if let Some(table) = intersection_table.as_ref() {
        encoder
            .set_intersection_function_table(table, 3)
            .expect("bind intersection function table");
    }
    if let Some(acceleration_structure) = acceleration_structure.as_ref() {
        encoder
            .set_acceleration_structure(acceleration_structure, 4)
            .expect("bind acceleration structure");
    }
    encoder
        .dispatch_threadgroups((1, 1, 1), (4, 1, 1))
        .expect("dispatch compute");
    if let Some(fence) = fence_b.as_ref() {
        encoder.update_fence(fence).expect("update fence");
    }
    encoder.end_encoding().expect("end compute encoder");
    compute.commit().expect("commit compute");
    compute.wait_until_completed().expect("complete compute");
    println!(
        "compute buffer after dispatch: {:?}",
        common::read_u32_words(&buffer, 4)
    );

    if let Some(indirect) = device.new_indirect_command_buffer(
        indirect_command_type::CONCURRENT_DISPATCH,
        1,
        0,
        0,
        4,
        resource_options::STORAGE_MODE_PRIVATE,
    ) {
        indirect.reset_range(0..1);
        println!("indirect command buffer size={}", indirect.size());
    }

    if let Some(heap) = device.new_heap(1 << 20, storage_mode::SHARED) {
        if let Ok(residency_set) = device.new_residency_set(Some("example-residency"), 4) {
            let heap_buffer = heap
                .new_buffer(256, resource_options::STORAGE_MODE_SHARED)
                .expect("heap buffer");
            residency_set.add_buffer(&heap_buffer);
            residency_set.add_heap(&heap);
            residency_set.commit();
            residency_set.request_residency();
            queue.add_residency_set(&residency_set);
            queue.remove_residency_set(&residency_set);
            residency_set.end_residency();
            residency_set.remove_all_allocations();
            residency_set.commit();
            println!(
                "residency allocation count={}",
                residency_set.allocation_count()
            );
        } else {
            println!("residency sets unavailable on this OS");
        }
    }

    if let Some(capture_manager) = CaptureManager::shared() {
        println!(
            "capture supported for developer tools={} active={}",
            capture_manager.supports_destination(capture_destination::DEVELOPER_TOOLS),
            capture_manager.is_capturing(),
        );
        if let Some(scope) = capture_manager.new_capture_scope_with_device(&device) {
            scope.begin();
            scope.end();
        }
        if let Some(scope) = capture_manager.new_capture_scope_with_command_queue(&queue) {
            scope.begin();
            scope.end();
        }
    }
}