Crate gfx_gtk

A bridge lib between gfx and gtk, which allows rendering [gtk::GlArea] content via gfx calls and its gl backend.

Uses epoxy for Gl loading, and as such it doesn't require a Gl window/loading management such as glutin or winit

See [https://github.com/itadinanta/gfx-gtk/blob/master/examples/setup.rs] for a simple rendering example.

Here's a short broken-down list to get the integration up and running:

Add the Cargo dependencies

[dependencies]
gfx_gtk = "0.3"

Import crate and packages

extern crate gfx_gtk;

use gfx_gtk::formats;
use gfx_gtk::GlRenderContext;

Choose some render formats and AA mode

const MSAA: gfx::texture::AaMode = formats::MSAA_4X;
type RenderColorFormat = formats::DefaultRenderColorFormat;
type RenderDepthFormat = formats::DefaultRenderDepthFormat;

Write a render callback

You need to implement GlRenderCallback and GlPostprocessCallback traits (the latter can be made to use the default implementation)

struct SimpleRenderCallback {
    ...
}

impl gfx_gtk::GlRenderCallback<RenderColorFormat, RenderDepthFormat> for SimpleRenderCallback {
    fn render(
        &mut self,
        gfx_context: &mut gfx_gtk::GlGfxContext,
        viewport: &gfx_gtk::Viewport,
        frame_buffer: &gfx_gtk::GlFrameBuffer<RenderColorFormat>,
        depth_buffer: &gfx_gtk::GlDepthBuffer<RenderDepthFormat>,
    ) -> gfx_gtk::Result<gfx_gtk::GlRenderCallbackStatus> {
        gfx_context.encoder.draw(...);
        Ok(gfx_gtk::GlRenderCallbackStatus::Continue)
    }
}

impl gfx_gtk::GlPostprocessCallback<RenderColorFormat, RenderDepthFormat> for SimpleRenderCallback {}

Load Gl functions

gfx_gtk::load();

Connect the widget's signals

The rendering needs to be driven by a GlArea widget because of its ability to create a Gl context.

The realize, resize and render signals need to be connected. The GlRenderContext and GlRenderCallback must be created in the closure that gets attached to GlArea::connect_realize() after the make_current() call (otherwise it won't be possible to "bind" to the current GlArea Gl context

let gfx_context: Rc<RefCell<Option<GlRenderContext<RenderColorFormat, RenderDepthFormat>>>> = Rc::new(RefCell::new(None));

let render_callback: Rc<RefCell<Option<SimpleRenderCallback>>> = Rc::new(RefCell::new(None));

let glarea = gtk::GLArea::new();

glarea.connect_realize({
    let gfx_context = gfx_context.clone();
    let render_callback = render_callback.clone();

    move |widget| {
        if widget.get_realized() {
            widget.make_current();
        }

        let allocation = widget.get_allocation();

        let mut new_context =
            gfx_gtk::GlRenderContext::new(
                MSAA,
                allocation.width,
                allocation.height,
                None).ok();
        if let Some(ref mut new_context) = new_context {
            let ref vp = new_context.viewport();
            let ref mut ctx = new_context.gfx_context_mut();
            *render_callback.borrow_mut() = SimpleRenderCallback::new(ctx, vp).ok();
        }
        *gfx_context.borrow_mut() = new_context;
    }
});

glarea.connect_resize({
    let gfx_context = gfx_context.clone();
    let render_callback = render_callback.clone();

    move |_widget, width, height| {
        if let Some(ref mut context) = *gfx_context.borrow_mut() {
            if let Some(ref mut render_callback) = *render_callback.borrow_mut() {
                context.resize(width, height, Some(render_callback)).ok();
            }
        }
    }
});

glarea.connect_render({
    let gfx_context = gfx_context.clone();
    let render_callback = render_callback.clone();

    move |_widget, _gl_context| {
        if let Some(ref mut context) = *gfx_context.borrow_mut() {
            if let Some(ref mut render_callback) = *render_callback.borrow_mut() {
                context.with_gfx(render_callback);
            }
        }

        Inhibit(false)
    }
});

After this, every time Gtk refreshes the GlArea content, it will invoke the render_callback to paint itself.

Modules

formats	Contains definitions of the default color and depth formats with an eye on compatibility with the GlArea render targets
postprocess
shaders	Predefined shaders used in postprocessing

Structs

BlitVertex
GfxContext	A container for a GL device and factory, with a convenience encoder ready to use. Typically, it will be specialised, including a GlDevice and GlFactory
PostprocessContext	a container for the pre-built data and state needed to perform MSAA resolution and sRGB correction in the post-processing stage
RenderContext	Structure encapsulating all the GFX state needed for rendering within a GL context in GTK
Viewport	Describes the client area of the GlArea being rendered into

Enums

Error	Error type for Result
GlRenderCallbackStatus	Hint returned at the end of Render and PostProcess calls. Returning Skip at the end of the render pass will bypass the postprocessing stage

Traits

FactoryExt	Extends gfx::traits::FactoryExt with utility functions specific to the gfx to gtk integration
GlPostprocessCallback	Implement custom post-processing behaviour for the GlArea
GlRenderCallback	Implement custom render behaviour for the GlArea

Functions

debug_load	Loads the Gl function pointers via epoxy, with some diagnostic output.
load	Loads the Gl function pointers via epoxy.

Type Definitions

Depth	Convenience type to express a floating point depth value as f32
Float4	Convenience type to express a general purpose vec4 [x,y,z,w] f32
GlCommandBuffer	gfx command buffer, Gl backend
GlDepthBuffer	gfx main depth buffer, Gl backend
GlDevice	gfx device, Gl backend
GlEncoder	gfx encoder, Gl backend
GlFactory	gfx factory, Gl backend
GlFrameBuffer	gfx main render target, Gl backend
GlFrameBufferTextureSrc	gfx texture source view of the main render target, Gl backend
GlGfxContext	Specialization of the GlRenderContext to be used with a Gl device
GlPostprocessContext	Specalization of the GlCallbackContext to be used with a Gl device
GlRenderContext	render context, specialized for the gfx Gl backend
GlResources	gfx resources, Gl backend
Result	Result which produces an Error on failure
Rgba	Convenience type to express a typical RGBA quantity as [r,g,b,a] f32