Crate gfx_gtk[][src]

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