cogl/auto/
display.rs

1use crate::{Object, OnscreenTemplate, Renderer};
2
3use glib::translate::*;
4use std::{fmt, ptr};
5
6glib_wrapper! {
7    pub struct Display(Object<ffi::CoglDisplay, DisplayClass>) @extends Object;
8
9    match fn {
10        get_type => || ffi::cogl_display_get_gtype(),
11    }
12}
13
14impl Display {
15    /// Explicitly allocates a new `Display` object to encapsulate the
16    /// common state of the display pipeline that applies to the whole
17    /// application.
18    ///
19    /// `<note>`Many applications don't need to explicitly use
20    /// `Display::new` and can just jump straight to `Context::new`
21    /// and pass a `None` display argument so Cogl will automatically
22    /// connect and setup a renderer and display.`</note>`
23    ///
24    /// A `display` can only be made for a specific choice of renderer which
25    /// is why this takes the `renderer` argument.
26    ///
27    /// A common use for explicitly allocating a display object is to
28    /// define a template for allocating onscreen framebuffers which is
29    /// what the `onscreen_template` argument is for, or alternatively
30    /// you can use `Display::set_onscreen_template`.
31    ///
32    /// When a display is first allocated via `Display::new` it is in a
33    /// mutable configuration mode. It's designed this way so we can
34    /// extend the apis available for configuring a display without
35    /// requiring huge numbers of constructor arguments.
36    ///
37    /// When you have finished configuring a display object you can
38    /// optionally call `Display::setup` to explicitly apply the
39    /// configuration and check for errors. Alternaitvely you can pass the
40    /// display to `Context::new` and Cogl will implicitly apply your
41    /// configuration but if there are errors then the application will
42    /// abort with a message. For simple applications with no fallback
43    /// options then relying on the implicit setup can be fine.
44    /// ## `renderer`
45    /// A `Renderer`
46    /// ## `onscreen_template`
47    /// A `OnscreenTemplate`
48    ///
49    /// # Returns
50    ///
51    /// A newly allocated `Display`
52    ///  object in a mutable configuration mode.
53    pub fn new(renderer: &Renderer, onscreen_template: &OnscreenTemplate) -> Display {
54        unsafe {
55            from_glib_full(ffi::cogl_display_new(
56                renderer.to_glib_none().0,
57                onscreen_template.to_glib_none().0,
58            ))
59        }
60    }
61
62    /// Queries the `Renderer` associated with the given `self`.
63    ///
64    /// # Returns
65    ///
66    /// The associated `Renderer`
67    pub fn get_renderer(&self) -> Option<Renderer> {
68        unsafe { from_glib_none(ffi::cogl_display_get_renderer(self.to_glib_none().0)) }
69    }
70
71    /// Specifies a template for creating `Onscreen` framebuffers.
72    ///
73    /// Depending on the system, the constraints for creating `Onscreen`
74    /// framebuffers need to be known before setting up a `Display` because the
75    /// final setup of the display may constrain how onscreen framebuffers may be
76    /// allocated. If Cogl knows how an application wants to allocate onscreen
77    /// framebuffers then it can try to make sure to setup the display accordingly.
78    /// ## `onscreen_template`
79    /// A template for creating `Onscreen` framebuffers
80    pub fn set_onscreen_template(&self, onscreen_template: &OnscreenTemplate) {
81        unsafe {
82            ffi::cogl_display_set_onscreen_template(
83                self.to_glib_none().0,
84                onscreen_template.to_glib_none().0,
85            );
86        }
87    }
88
89    /// Explicitly sets up the given `self` object. Use of this api is
90    /// optional since Cogl will internally setup the display if not done
91    /// explicitly.
92    ///
93    /// When a display is first allocated via `Display::new` it is in a
94    /// mutable configuration mode. This allows us to extend the apis
95    /// available for configuring a display without requiring huge numbers
96    /// of constructor arguments.
97    ///
98    /// Its possible to request a configuration that might not be
99    /// supportable on the current system and so this api provides a means
100    /// to apply the configuration explicitly but if it fails then an
101    /// exception will be returned so you can handle the error gracefully
102    /// and perhaps fall back to an alternative configuration.
103    ///
104    /// If you instead rely on Cogl implicitly calling `Display::setup`
105    /// for you then if there is an error with the configuration you won't
106    /// get an opportunity to handle that and the application may abort
107    /// with a message. For simple applications that don't have any
108    /// fallback options this behaviour may be fine.
109    ///
110    /// # Returns
111    ///
112    /// Returns `true` if there was no error, else it returns
113    ///  `false` and returns an exception via `error`.
114    pub fn setup(&self) -> Result<bool, glib::Error> {
115        unsafe {
116            let mut error = ptr::null_mut();
117            let ret = ffi::cogl_display_setup(self.to_glib_none().0, &mut error);
118            if error.is_null() {
119                Ok(ret == crate::TRUE)
120            } else {
121                Err(from_glib_full(error))
122            }
123        }
124    }
125}
126
127impl fmt::Display for Display {
128    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
129        write!(f, "Display")
130    }
131}
cogl/auto/display.rs

cogl/auto/
display.rs
