Struct Context 

pub struct Context(/* private fields */);

An Impeller graphics context. Contexts are platform and client-rendering-API specific.

Contexts are thread-safe objects (not thread-safe with openGL) that are expensive to create. Most applications will only ever create a single context during their lifetimes. Once setup, Impeller is ready to render frames as performantly as possible.

During setup, context create the underlying graphics pipelines, allocators, worker threads, etc…

The general guidance is to create as few contexts as possible (typically just one) and share them as much as possible.

Implementations

impl Context

pub unsafe fn new_opengl_es<F: FnMut(&str) -> *mut c_void>( gl_proc_address: F, ) -> Result<Context, &'static str>

Create an OpenGL(ES) Impeller context.

@param

• gl_proc_address: A closure that returns the address of GL fn pointers

@return The context or error if the context could not be created.

fn create_impeller_ctx(window: &mut glfw::PWindow) {
    // as easy as it gets
    let impeller_ctx = unsafe {
        // safety:  drop all objects created from this context
        //          before `window` is dropped
        impellers::Context::new_opengl_es( |name| {
            window.get_proc_address(name) as _
        })
    };

}

Safety

• The context must be dropped before the underlying window is dropped.
• The context may only be used while the underlying context is current on the thread.
• Any object (like texture or surface) that you create using this context must be dropped before the context is dropped.
• Unlike other context types, the OpenGL ES context can only be created, used, and collected on the calling thread. This restriction may be lifted in the future once reactor workers are exposed in the API. No other context types have threading restrictions. Till reactor workers can be used, using the context on a background thread will cause a stall of OpenGL operations.

Examples found in repository

examples/common.rs (line 42)

    pub fn new() -> Self {
        // initialize window
        let mut gtx = init(fail_on_errors).expect("failed to init glfw");
        gtx.window_hint(WindowHint::ContextVersionMajor(4));
        gtx.window_hint(WindowHint::OpenGlProfile(OpenGlProfileHint::Core));
        gtx.window_hint(WindowHint::SRgbCapable(true));
        gtx.window_hint(WindowHint::StencilBits(Some(8)));
        gtx.window_hint(WindowHint::ScaleToMonitor(true));

        let (mut window, ev_receiver) = gtx
            .create_window(800, 600, "glfw opengl impeller", WindowMode::Windowed)
            .unwrap();
        window.make_current();
        window.set_all_polling(true);

        // initialize impeller context using opengl fn pointers
        let itx = unsafe { impellers::Context::new_opengl_es(|s| window.get_proc_address(s) as _) }
            .unwrap();
        let glow_ctx =
            unsafe { glow::Context::from_loader_function(|s| window.get_proc_address(s) as _) };
        unsafe {
            let (width, height) = window.get_framebuffer_size();
            glow_ctx.viewport(0, 0, width, height);
        }
        let ttx = TypographyContext::default();
        let mut style = ParagraphStyle::default();
        style.set_font_size(24.0);
        style.set_font_family("Roboto");
        style.set_font_weight(FontWeight::Bold);
        let mut paint = Paint::default();
        paint.set_color(Color::LIGHT_SKY_BLUE);
        style.set_foreground(&paint);
        Self {
            ttx,
            style,
            glow_ctx,
            itx,
            window,
            receiver: ev_receiver,
            gtx,
            events: vec![],
        }
    }

examples/hello.rs (line 19)

pub fn main() {
    let mut gtx = init(fail_on_errors).unwrap();
    gtx.window_hint(WindowHint::OpenGlProfile(OpenGlProfileHint::Core));
    gtx.window_hint(WindowHint::ContextVersionMajor(4));
    gtx.window_hint(WindowHint::SRgbCapable(true));
    gtx.window_hint(WindowHint::ScaleToMonitor(true));
    let (mut window, ev_receiver) = gtx
        .create_window(800, 600, "rust-glfw-impeller demo", WindowMode::Windowed)
        .expect("failed to create window");
    window.set_all_polling(true);
    window.make_current();

    // initialize impeller context using opengl fn pointers
    let mut itx =
        unsafe { impellers::Context::new_opengl_es(|s| window.get_proc_address(s) as _) }.unwrap();
    let glow_ctx: glow::Context =
        unsafe { glow::Context::from_loader_function(|s| window.get_proc_address(s)) as _ };
    // enter event loop
    while !window.should_close() {
        // check events
        gtx.poll_events();
        for (_, event) in flush_messages(&ev_receiver) {
            match event {
                WindowEvent::Close => {
                    window.set_should_close(true);
                }
                WindowEvent::FramebufferSize(_, _) => {
                    // glViewPort here
                }
                _ => {}
            }
        }

        let (width, height) = window.get_framebuffer_size();
        let mut surface = unsafe {
            itx.wrap_fbo(
                0,
                PixelFormat::RGBA8888,
                ISize::new(width.into(), height.into()),
            )
        }
        .expect("failed to wrap window's framebuffer");
        // create a display list
        let clear_display_list = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            // eg: lets set the color to black. So, any drawing command with this paint will use that color.
            paint.set_color(Color::BLACKBERRY);
            // fill the bounds with a color (^^that we set above)
            builder.draw_paint(&paint);
            let current_time = gtx.get_time(); // time in seconds since start of the program
                                               // lets set the color to a color that changes with time.
                                               // sin/cos/tan will always be in the range of -1 to 1, so lets use abs to keep it in between 0 and 1.
            paint.set_color(Color::new_srgb(
                current_time.sin().abs() as _,
                current_time.cos().abs() as _,
                current_time.tan().abs() as _,
            ));
            builder.draw_rect(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let animating_dl = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            let current_time = gtx.get_time(); // time in seconds since start of the program
                                               // lets set the color to a color that changes with time.
                                               // sin/cos/tan will always be in the range of -1 to 1, so lets use abs to keep it in between 0 and 1.
            paint.set_color(Color::new_srgb(
                current_time.sin().abs() as _,
                current_time.cos().abs() as _,
                current_time.tan().abs() as _,
            ));
            builder.draw_rect(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let oval_dl = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            // eg: lets set the color to black. So, any drawing command with this paint will use that color.
            paint.set_color(Color::GRANNY_APPLE);
            builder.draw_oval(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let main_display_list = {
            let mut builder = DisplayListBuilder::new(None);
            builder.draw_display_list(&clear_display_list, 1.0);
            builder.draw_display_list(&animating_dl, 1.0);
            builder.draw_display_list(&oval_dl, 1.0);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        // Now, draw the display_list on the surface. All the commands we recorded in the display_list will be drawn.
        // you can redraw the display_list multiple times to animate it on any number of surfaces.
        unsafe {
            glow_ctx.clear_color(1.0, 0.0, 0.0, 1.0);
            glow_ctx.clear(glow::COLOR_BUFFER_BIT);
        }
        surface
            .draw_display_list(&main_display_list)
            .expect("failed to draw on surface");
        // submit frame and wait for vsync
        window.swap_buffers();
    }

    // drop the window/sdl or whatever
}

pub unsafe fn wrap_fbo( &mut self, fbo: u64, format: PixelFormat, size: ISize, ) -> Option<Surface>

Create a new surface by wrapping an existing framebuffer object. The surface is just a cheap use-and-throw object. Create it, draw to it (once) and drop it .

• fbo The framebuffer object handle.
• format The format of the framebuffer.
• size The size of the framebuffer is texels.

@return The surface if once can be created, NULL otherwise.

Safety

• The surface must be properly configured (eg: no pending resizes)
• must be drawn to only once and then dropped (presented if vulkan).
• must be dropped before the context is dropped
• The framebuffer must be complete as determined by glCheckFramebufferStatus. The framebuffer is still owned by the caller and it must be collected once the surface is collected.

Examples found in repository

examples/common.rs (lines 127-131)

    pub fn enter_event_loop(
        mut self,
        dl: Option<DisplayList>,
        mut user_callback: Option<UserCallback>,
    ) {
        let mut previous_instant = std::time::Instant::now();
        let mut current_frame = 0;
        let mut fps = 0;
        let mut vsync = true;
        // enter event loop
        while !self.window.should_close() {
            {
                // record fps
                if previous_instant.elapsed().as_secs_f64() >= 1.0 {
                    fps = current_frame;
                    current_frame = 0;
                    previous_instant = std::time::Instant::now();
                }
                current_frame += 1;
            }
            self.events.clear();
            // check events
            self.gtx.poll_events();
            for (_, event) in flush_messages(&self.receiver) {
                match &event {
                    WindowEvent::Close => {
                        self.window.set_should_close(true);
                    }
                    WindowEvent::FramebufferSize(w, h) => {
                        unsafe {
                            self.glow_ctx.viewport(0, 0, *w, *h);
                        }
                        println!("window resized to {}x{}", w, h);
                    }
                    WindowEvent::Key(Key::Space, _, Action::Release, _) => {
                        vsync = !vsync;
                        println!("setting vsync to {vsync}");

                        self.gtx.set_swap_interval(if vsync {
                            SwapInterval::Sync(1)
                        } else {
                            SwapInterval::None
                        });
                    }
                    _ => {}
                }
                self.events.push(event);
            }

            let (width, height) = self.window.get_framebuffer_size();
            // init surface by wrapping default framebuffer (fbo = 0)
            let mut surface = unsafe {
                self.itx.wrap_fbo(
                    0,
                    PixelFormat::RGBA8888,
                    ISize::new(width.into(), height.into()),
                )
            }
            .expect("failed to wrap window's framebuffer");
            let mut dl_builder = DisplayListBuilder::new(Some(&Rect::from_size(
                [width as f32, height as f32].into(),
            )));

            if let Some(dl) = dl.as_ref() {
                dl_builder.draw_display_list(dl, 1.0);
            }
            // call user callback
            if let Some(cb) = user_callback.as_mut() {
                if let Some(display_list) = cb(&mut self) {
                    dl_builder.draw_display_list(&display_list, 1.0);
                }
            }
            {
                let mut para_builder = ParagraphBuilder::new(&self.ttx).unwrap();
                para_builder.push_style(&self.style);
                para_builder.add_text(&format!("avg fps: {fps}"));
                let para = para_builder.build(1000.0).unwrap();
                dl_builder.draw_paragraph(&para, Point::origin());
            }
            surface
                .draw_display_list(&dl_builder.build().unwrap())
                .unwrap();

            // submit frame and wait for vsync
            self.window.swap_buffers();
        }
    }

examples/hello.rs (lines 40-44)

pub fn main() {
    let mut gtx = init(fail_on_errors).unwrap();
    gtx.window_hint(WindowHint::OpenGlProfile(OpenGlProfileHint::Core));
    gtx.window_hint(WindowHint::ContextVersionMajor(4));
    gtx.window_hint(WindowHint::SRgbCapable(true));
    gtx.window_hint(WindowHint::ScaleToMonitor(true));
    let (mut window, ev_receiver) = gtx
        .create_window(800, 600, "rust-glfw-impeller demo", WindowMode::Windowed)
        .expect("failed to create window");
    window.set_all_polling(true);
    window.make_current();

    // initialize impeller context using opengl fn pointers
    let mut itx =
        unsafe { impellers::Context::new_opengl_es(|s| window.get_proc_address(s) as _) }.unwrap();
    let glow_ctx: glow::Context =
        unsafe { glow::Context::from_loader_function(|s| window.get_proc_address(s)) as _ };
    // enter event loop
    while !window.should_close() {
        // check events
        gtx.poll_events();
        for (_, event) in flush_messages(&ev_receiver) {
            match event {
                WindowEvent::Close => {
                    window.set_should_close(true);
                }
                WindowEvent::FramebufferSize(_, _) => {
                    // glViewPort here
                }
                _ => {}
            }
        }

        let (width, height) = window.get_framebuffer_size();
        let mut surface = unsafe {
            itx.wrap_fbo(
                0,
                PixelFormat::RGBA8888,
                ISize::new(width.into(), height.into()),
            )
        }
        .expect("failed to wrap window's framebuffer");
        // create a display list
        let clear_display_list = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            // eg: lets set the color to black. So, any drawing command with this paint will use that color.
            paint.set_color(Color::BLACKBERRY);
            // fill the bounds with a color (^^that we set above)
            builder.draw_paint(&paint);
            let current_time = gtx.get_time(); // time in seconds since start of the program
                                               // lets set the color to a color that changes with time.
                                               // sin/cos/tan will always be in the range of -1 to 1, so lets use abs to keep it in between 0 and 1.
            paint.set_color(Color::new_srgb(
                current_time.sin().abs() as _,
                current_time.cos().abs() as _,
                current_time.tan().abs() as _,
            ));
            builder.draw_rect(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let animating_dl = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            let current_time = gtx.get_time(); // time in seconds since start of the program
                                               // lets set the color to a color that changes with time.
                                               // sin/cos/tan will always be in the range of -1 to 1, so lets use abs to keep it in between 0 and 1.
            paint.set_color(Color::new_srgb(
                current_time.sin().abs() as _,
                current_time.cos().abs() as _,
                current_time.tan().abs() as _,
            ));
            builder.draw_rect(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let oval_dl = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            // eg: lets set the color to black. So, any drawing command with this paint will use that color.
            paint.set_color(Color::GRANNY_APPLE);
            builder.draw_oval(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let main_display_list = {
            let mut builder = DisplayListBuilder::new(None);
            builder.draw_display_list(&clear_display_list, 1.0);
            builder.draw_display_list(&animating_dl, 1.0);
            builder.draw_display_list(&oval_dl, 1.0);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        // Now, draw the display_list on the surface. All the commands we recorded in the display_list will be drawn.
        // you can redraw the display_list multiple times to animate it on any number of surfaces.
        unsafe {
            glow_ctx.clear_color(1.0, 0.0, 0.0, 1.0);
            glow_ctx.clear(glow::COLOR_BUFFER_BIT);
        }
        surface
            .draw_display_list(&main_display_list)
            .expect("failed to draw on surface");
        // submit frame and wait for vsync
        window.swap_buffers();
    }

    // drop the window/sdl or whatever
}

pub unsafe fn create_texture_with_rgba8( &self, contents: Cow<'static, [u8]>, width: u32, height: u32, ) -> Result<Texture, &'static str>

Create a texture with decompressed bytes.

@warning Do not supply compressed image data directly (PNG, JPEG, etc…). This function only works with tightly packed decompressed data. @param

• contents texture bytes. contiguously laid out as RGBA8888
• width width of texture
• height height of texture

@return The texture if one can be created using the provided data, NULL otherwise.

Safety

• The texture must be dropped before the context is dropped

Examples found in repository

examples/backdrop_blur.rs (line 22)

fn main() {
    let framework = common::SdlGlImpellerFrameWork::new();
    let (width, height) = framework.window.get_framebuffer_size();
    //  we resize the image so that it fits within our window
    let pixels = image::load_from_memory(common::DOG_BYTES)
        .unwrap()
        .resize(
            width as _,
            height as _,
            image::imageops::FilterType::Triangle,
        )
        .into_rgba8();

    let (width, height) = pixels.dimensions();
    let contents = pixels.into_raw();
    let tex = unsafe {
        framework
            .itx
            .create_texture_with_rgba8(contents.into(), width, height)
            .unwrap()
    };
    let dl = {
        let mut builder = DisplayListBuilder::new(None);
        let paint = Paint::default();
        builder.draw_texture(&tex, Point::zero(), TextureSampling::Linear, &paint);

        let rect = Rect::new(Point::zero(), Size::new(width as f32, height as f32 / 2.0));
        builder.clip_rect(&rect, ClipOperation::Intersect);
        // the backdrop will be blurred by this (within the clip area set above)
        builder.save_layer(
            &rect,
            None,
            Some(&ImageFilter::new_blur(8.0, 8.0, TileMode::Clamp)),
        );
        // no need to do anything
        builder.restore();
        builder.build().unwrap()
    };
    framework.enter_event_loop(Some(dl), None);
}

examples/star_clip.rs (line 13)

fn main() {
    let framework = common::SdlGlImpellerFrameWork::new();
    let pixels = image::load_from_memory(IMAGE_BYTES).unwrap().to_rgba8();
    let (width, height) = pixels.dimensions();
    let contents = pixels.into_raw();
    let tex = unsafe {
        framework
            .itx
            .create_texture_with_rgba8(contents.into(), width, height)
            .unwrap()
    };
    let dl = {
        let mut builder = DisplayListBuilder::new(None);

        // the rect inside image that contains the dog.
        let dog_rect = Rect::new([700.0, 500.0].into(), [600.0, 500.0].into());
        // where on canvas we will be drawing the above rect's texture contents
        // always a good idea to keep the scaling proportional.
        // the width and height are 600x500 from src_rect, so, we use widthxheight of 300x250 for dst_rect
        // The scaling will be uniform. The reason for 250 height is that our star will also roughly be 256x256 sized.
        let dst_rect = Rect::from_size([300.0, 250.0].into());

        let path = {
            // build a star path
            let mut path_builder = PathBuilder::default();
            path_builder.move_to([128.0, 0.0].into());
            path_builder.line_to([168.0, 80.0].into());
            path_builder.line_to([256.0, 93.0].into());
            path_builder.line_to([192.0, 155.0].into());
            path_builder.line_to([207.0, 244.0].into());
            path_builder.line_to([128.0, 202.0].into());
            path_builder.line_to([49.0, 244.0].into());
            path_builder.line_to([64.0, 155.0].into());
            path_builder.line_to([0.0, 93.0].into());
            path_builder.line_to([88.0, 80.0].into());
            path_builder.line_to([128.0, 0.0].into());
            path_builder.close();
            path_builder.take_path_new(FillType::NonZero)
        };
        {
            // clear screen
            let mut paint = Paint::default();
            paint.set_color(Color::BLACK);
            builder.draw_paint(&paint);
        }
        // first, lets clip so that only contents *inside* will be visible.
        {
            // always a good idea to push a new stack and work there.
            // Then, pop after you are done drawing.
            builder.save();
            // intersect ensures that only the inside of the clip is drawn (if it overlaps with the clips down the stack)
            builder.clip_path(&path, ClipOperation::Intersect);
            builder.draw_texture_rect(&tex, &dog_rect, &dst_rect, TextureSampling::Linear, None);
            builder.restore(); // clip is gone here.
        }
        {
            builder.save();
            // lets move to right, so we don't draw over the previous contents.
            builder.translate(300.0, 0.0);
            // difference ensures that the clip is inverted and nothing will be drawn *inside*
            builder.clip_path(&path, ClipOperation::Difference);
            builder.draw_texture_rect(&tex, &dog_rect, &dst_rect, TextureSampling::Linear, None);
            builder.restore(); // clip and translate are popped off stack
        }
        builder.build().unwrap()
    };
    framework.enter_event_loop(Some(dl), None);
}

pub unsafe fn adopt_opengl_texture( &self, width: u32, height: u32, mip_count: u32, handle: u64, ) -> Option<Texture>

Create a texture with an externally created OpenGL texture handle.

• width width of texture
• height height of texture
• mip_count mipcount of texture
• handle The handle

@return The texture if one could be created by adopting the supplied texture handle, NULL otherwise.

Safety

• The texture must be dropped before the context is dropped

• Ownership of the handle is transferred over to Impeller after a successful call to this method. Impeller is responsible for calling glDeleteTextures on this handle. Do not collect this handle yourself as this will lead to a double-free.

• The handle must be created in the same context as the one used by Impeller. If a different context is used, that context must be in the same sharegroup as Impellers OpenGL context and all synchronization of texture contents must already be complete.

If the context is not an OpenGL context, this call will always fail.

pub unsafe fn new_metal() -> Result<Context, &'static str>

Create a Metal context using the system default Metal device.

Safety

I don’t know much about Metal, so I will leave the work of figuring out the safety to users. good luck :)

@return The Metal context or NULL if one cannot be created.

pub unsafe fn new_vulkan<F: FnMut(*mut c_void, *const c_char) -> *mut c_void>( enable_validation: bool, proc_address_callback: F, ) -> Result<Context, &'static str>

Create a Vulkan context using the provided Vulkan Settings.

• enable_validation Enable Vulkan validation layers
• proc_address_callback A callback to query the address of Vulkan function pointers. The first argument is a pointer to vulkan instance. The second argument is a pointer to the function name.

@return The Vulkan context or NULL if one cannot be created.

Safety

Don’t know much vulkan either, so users will have to figure out the safety invariants.

Just look at vulkan docs for how your proc_address_callback should work. Don’t hold on to any pointers given to your closure (instance pointer or char pointer).

Examples found in repository

examples/glfw_vulkan.rs (lines 18-24)

pub fn main() {
    let mut gtx = init(fail_on_errors).unwrap();
    gtx.window_hint(WindowHint::ClientApi(ClientApiHint::NoApi));
    gtx.window_hint(WindowHint::ScaleToMonitor(true));
    let (mut window, ev_receiver) = gtx
        .create_window(800, 600, "rust-glfw-impeller demo", WindowMode::Windowed)
        .expect("failed to create window");
    window.set_all_polling(true);

    // initialize impeller context by loading vulkan fn pointers
    let itx = unsafe {
        assert!(gtx.vulkan_supported());
        // create context using callback
        impellers::Context::new_vulkan(false, |vk_instance, vk_proc_name| {
            let proc_name = std::ffi::CStr::from_ptr(vk_proc_name).to_str().unwrap();
            gtx.get_instance_proc_address_raw(
                ash::vk::Instance::from_raw(vk_instance as _),
                proc_name,
            ) as _
        })
    }
    .expect("failed to create impeller context");
    // lets see what's in here
    let vk_info = itx.get_vulkan_info().expect("failed to get vulkan info");
    dbg!(vk_info);
    assert!(
        !vk_info.vk_instance.is_null(),
        "instance pointer from vulkan info is null"
    );

    let mut vulkan_surface_khr: ash::vk::SurfaceKHR = ash::vk::SurfaceKHR::null();
    window
        .create_window_surface(
            ash::vk::Instance::from_raw(vk_info.vk_instance as _),
            std::ptr::null(),
            &raw mut vulkan_surface_khr,
        )
        .result()
        .expect("failed to create vk surface khr");
    assert!(!vulkan_surface_khr.is_null(), "surface pointer is null");
    let mut vk_swapchain =
        unsafe { itx.create_new_vulkan_swapchain(vulkan_surface_khr.as_raw() as _) }
            .expect("failed to create vk swapchain");

    // enter event loop
    while !window.should_close() {
        // check events
        gtx.poll_events();
        for (_, event) in flush_messages(&ev_receiver) {
            if event == WindowEvent::Close {
                window.set_should_close(true);
            }
        }

        let clear_display_list = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            // eg: lets set the color to black. So, any drawing command with this paint will use that color.
            paint.set_color(Color::BLACKBERRY);
            // fill the bounds with a color (^^that we set above)
            builder.draw_paint(&paint);
            let current_time = gtx.get_time(); // time in seconds since start of the program
                                               // lets set the color to a color that changes with time.
                                               // sin/cos/tan will always be in the range of -1 to 1, so lets use abs to keep it in between 0 and 1.
            paint.set_color(Color::new_srgb(
                current_time.sin().abs() as _,
                current_time.cos().abs() as _,
                current_time.tan().abs() as _,
            ));
            builder.draw_rect(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let animating_dl = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            let current_time = gtx.get_time(); // time in seconds since start of the program
                                               // lets set the color to a color that changes with time.
                                               // sin/cos/tan will always be in the range of -1 to 1, so lets use abs to keep it in between 0 and 1.
            paint.set_color(Color::new_srgb(
                current_time.sin().abs() as _,
                current_time.cos().abs() as _,
                current_time.tan().abs() as _,
            ));
            builder.draw_rect(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let oval_dl = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            // eg: lets set the color to black. So, any drawing command with this paint will use that color.
            paint.set_color(Color::GRANNY_APPLE);
            builder.draw_oval(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let main_display_list = {
            let mut builder = DisplayListBuilder::new(None);
            builder.draw_display_list(&clear_display_list, 1.0);
            builder.draw_display_list(&animating_dl, 1.0);
            builder.draw_display_list(&oval_dl, 1.0);
            builder.build().expect("failed to build a display_list")
        };
        let mut surface = vk_swapchain.acquire_next_surface_new().unwrap();
        // Now, draw the display_list on the surface. All the commands we recorded in the display_list will be drawn.
        // you can redraw the display_list multiple times to animate it on any number of surfaces.

        surface
            .draw_display_list(&main_display_list)
            .expect("failed to draw on surface");
        // submit frame and wait for vsync
        surface.present().unwrap();
    }

    // drop the window/sdl or whatever
}

pub fn get_vulkan_info(&self) -> Result<VulkanInfo, &'static str>

Get internal Vulkan handles managed by the given Vulkan context. Ownership of the handles is still maintained by Impeller. This accessor is just available so embedders can create resources using the same device and instance as Impeller for interop.

@warning If the context is not a Vulkan context, this will return Err.

Examples found in repository

examples/glfw_vulkan.rs (line 28)

pub fn main() {
    let mut gtx = init(fail_on_errors).unwrap();
    gtx.window_hint(WindowHint::ClientApi(ClientApiHint::NoApi));
    gtx.window_hint(WindowHint::ScaleToMonitor(true));
    let (mut window, ev_receiver) = gtx
        .create_window(800, 600, "rust-glfw-impeller demo", WindowMode::Windowed)
        .expect("failed to create window");
    window.set_all_polling(true);

    // initialize impeller context by loading vulkan fn pointers
    let itx = unsafe {
        assert!(gtx.vulkan_supported());
        // create context using callback
        impellers::Context::new_vulkan(false, |vk_instance, vk_proc_name| {
            let proc_name = std::ffi::CStr::from_ptr(vk_proc_name).to_str().unwrap();
            gtx.get_instance_proc_address_raw(
                ash::vk::Instance::from_raw(vk_instance as _),
                proc_name,
            ) as _
        })
    }
    .expect("failed to create impeller context");
    // lets see what's in here
    let vk_info = itx.get_vulkan_info().expect("failed to get vulkan info");
    dbg!(vk_info);
    assert!(
        !vk_info.vk_instance.is_null(),
        "instance pointer from vulkan info is null"
    );

    let mut vulkan_surface_khr: ash::vk::SurfaceKHR = ash::vk::SurfaceKHR::null();
    window
        .create_window_surface(
            ash::vk::Instance::from_raw(vk_info.vk_instance as _),
            std::ptr::null(),
            &raw mut vulkan_surface_khr,
        )
        .result()
        .expect("failed to create vk surface khr");
    assert!(!vulkan_surface_khr.is_null(), "surface pointer is null");
    let mut vk_swapchain =
        unsafe { itx.create_new_vulkan_swapchain(vulkan_surface_khr.as_raw() as _) }
            .expect("failed to create vk swapchain");

    // enter event loop
    while !window.should_close() {
        // check events
        gtx.poll_events();
        for (_, event) in flush_messages(&ev_receiver) {
            if event == WindowEvent::Close {
                window.set_should_close(true);
            }
        }

        let clear_display_list = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            // eg: lets set the color to black. So, any drawing command with this paint will use that color.
            paint.set_color(Color::BLACKBERRY);
            // fill the bounds with a color (^^that we set above)
            builder.draw_paint(&paint);
            let current_time = gtx.get_time(); // time in seconds since start of the program
                                               // lets set the color to a color that changes with time.
                                               // sin/cos/tan will always be in the range of -1 to 1, so lets use abs to keep it in between 0 and 1.
            paint.set_color(Color::new_srgb(
                current_time.sin().abs() as _,
                current_time.cos().abs() as _,
                current_time.tan().abs() as _,
            ));
            builder.draw_rect(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let animating_dl = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            let current_time = gtx.get_time(); // time in seconds since start of the program
                                               // lets set the color to a color that changes with time.
                                               // sin/cos/tan will always be in the range of -1 to 1, so lets use abs to keep it in between 0 and 1.
            paint.set_color(Color::new_srgb(
                current_time.sin().abs() as _,
                current_time.cos().abs() as _,
                current_time.tan().abs() as _,
            ));
            builder.draw_rect(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let oval_dl = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            // eg: lets set the color to black. So, any drawing command with this paint will use that color.
            paint.set_color(Color::GRANNY_APPLE);
            builder.draw_oval(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let main_display_list = {
            let mut builder = DisplayListBuilder::new(None);
            builder.draw_display_list(&clear_display_list, 1.0);
            builder.draw_display_list(&animating_dl, 1.0);
            builder.draw_display_list(&oval_dl, 1.0);
            builder.build().expect("failed to build a display_list")
        };
        let mut surface = vk_swapchain.acquire_next_surface_new().unwrap();
        // Now, draw the display_list on the surface. All the commands we recorded in the display_list will be drawn.
        // you can redraw the display_list multiple times to animate it on any number of surfaces.

        surface
            .draw_display_list(&main_display_list)
            .expect("failed to draw on surface");
        // submit frame and wait for vsync
        surface.present().unwrap();
    }

    // drop the window/sdl or whatever
}

pub unsafe fn create_new_vulkan_swapchain( &self, vulkan_surface_khr: *mut c_void, ) -> Option<VkSwapChain>

Create a new Vulkan swapchain using a VkSurfaceKHR instance. Ownership of the surface is transferred over to Impeller.

• vulkan_surface_khr The vulkan surface.

@return The vulkan swapchain.

Safety

The Vulkan instance the surface is created from must the same as the context provided.

The context must be a Vulkan context whose instance is the same used to create the surface passed into the next argument.

The surface pointer must be valid (and kept alive until this swapchain is dropped).

Examples found in repository

examples/glfw_vulkan.rs (line 46)

pub fn main() {
    let mut gtx = init(fail_on_errors).unwrap();
    gtx.window_hint(WindowHint::ClientApi(ClientApiHint::NoApi));
    gtx.window_hint(WindowHint::ScaleToMonitor(true));
    let (mut window, ev_receiver) = gtx
        .create_window(800, 600, "rust-glfw-impeller demo", WindowMode::Windowed)
        .expect("failed to create window");
    window.set_all_polling(true);

    // initialize impeller context by loading vulkan fn pointers
    let itx = unsafe {
        assert!(gtx.vulkan_supported());
        // create context using callback
        impellers::Context::new_vulkan(false, |vk_instance, vk_proc_name| {
            let proc_name = std::ffi::CStr::from_ptr(vk_proc_name).to_str().unwrap();
            gtx.get_instance_proc_address_raw(
                ash::vk::Instance::from_raw(vk_instance as _),
                proc_name,
            ) as _
        })
    }
    .expect("failed to create impeller context");
    // lets see what's in here
    let vk_info = itx.get_vulkan_info().expect("failed to get vulkan info");
    dbg!(vk_info);
    assert!(
        !vk_info.vk_instance.is_null(),
        "instance pointer from vulkan info is null"
    );

    let mut vulkan_surface_khr: ash::vk::SurfaceKHR = ash::vk::SurfaceKHR::null();
    window
        .create_window_surface(
            ash::vk::Instance::from_raw(vk_info.vk_instance as _),
            std::ptr::null(),
            &raw mut vulkan_surface_khr,
        )
        .result()
        .expect("failed to create vk surface khr");
    assert!(!vulkan_surface_khr.is_null(), "surface pointer is null");
    let mut vk_swapchain =
        unsafe { itx.create_new_vulkan_swapchain(vulkan_surface_khr.as_raw() as _) }
            .expect("failed to create vk swapchain");

    // enter event loop
    while !window.should_close() {
        // check events
        gtx.poll_events();
        for (_, event) in flush_messages(&ev_receiver) {
            if event == WindowEvent::Close {
                window.set_should_close(true);
            }
        }

        let clear_display_list = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            // eg: lets set the color to black. So, any drawing command with this paint will use that color.
            paint.set_color(Color::BLACKBERRY);
            // fill the bounds with a color (^^that we set above)
            builder.draw_paint(&paint);
            let current_time = gtx.get_time(); // time in seconds since start of the program
                                               // lets set the color to a color that changes with time.
                                               // sin/cos/tan will always be in the range of -1 to 1, so lets use abs to keep it in between 0 and 1.
            paint.set_color(Color::new_srgb(
                current_time.sin().abs() as _,
                current_time.cos().abs() as _,
                current_time.tan().abs() as _,
            ));
            builder.draw_rect(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let animating_dl = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            let current_time = gtx.get_time(); // time in seconds since start of the program
                                               // lets set the color to a color that changes with time.
                                               // sin/cos/tan will always be in the range of -1 to 1, so lets use abs to keep it in between 0 and 1.
            paint.set_color(Color::new_srgb(
                current_time.sin().abs() as _,
                current_time.cos().abs() as _,
                current_time.tan().abs() as _,
            ));
            builder.draw_rect(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let oval_dl = {
            // create a display list builder
            let mut builder = DisplayListBuilder::new(None);
            // paint controls the properties of draw commands
            let mut paint = Paint::default();
            // eg: lets set the color to black. So, any drawing command with this paint will use that color.
            paint.set_color(Color::GRANNY_APPLE);
            builder.draw_oval(&Rect::from_size(Size::new(200.0, 200.0)), &paint);
            // finish recording the drawing commands. This is only a "list" and we haven't drawn anything yet.
            builder.build().expect("failed to build a display_list")
        };
        let main_display_list = {
            let mut builder = DisplayListBuilder::new(None);
            builder.draw_display_list(&clear_display_list, 1.0);
            builder.draw_display_list(&animating_dl, 1.0);
            builder.draw_display_list(&oval_dl, 1.0);
            builder.build().expect("failed to build a display_list")
        };
        let mut surface = vk_swapchain.acquire_next_surface_new().unwrap();
        // Now, draw the display_list on the surface. All the commands we recorded in the display_list will be drawn.
        // you can redraw the display_list multiple times to animate it on any number of surfaces.

        surface
            .draw_display_list(&main_display_list)
            .expect("failed to draw on surface");
        // submit frame and wait for vsync
        surface.present().unwrap();
    }

    // drop the window/sdl or whatever
}

pub unsafe fn wrap_metal_drawable( &self, metal_drawable: *mut c_void, ) -> Option<Surface>

Create a surface by wrapping a Metal drawable. This is useful during WSI when the drawable is the backing store of the Metal layer being drawn to.

Safety

The Metal layer must be using the same device managed by the underlying context.

The Metal device managed by this context must be the same used to create the drawable that is being wrapped.

• metal_drawable The drawable to wrap as a surface.

@return The surface if one could be wrapped, NULL otherwise.

pub unsafe fn new_color_source_from_fragment_program( &self, frag_program: &FragmentProgram, samplers: &[Texture], uniform_data: &[u8], ) -> ColorSource

Create a color source whose pixels are shaded by a fragment program.

https://docs.flutter.dev/ui/design/graphics/fragment-shaders

Safety

Make sure the uniform data is laid out according to the fragment program’s requirements

TODO: add an example and better docs

pub unsafe fn new_image_filter_from_fragment_program( &self, frag_program: &FragmentProgram, samplers: &[Texture], uniform_data: &[u8], ) -> ImageFilter

Create an image filter where each pixel is shaded by a fragment program.

https://docs.flutter.dev/ui/design/graphics/fragment-shaders

Safety

Make sure the uniform data is laid out according to the fragment program’s requirements

TODO: add an example and better docs

Trait Implementations

impl Debug for Context

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Context

fn drop(&mut self)

Executes the destructor for this type.