gdk/auto/

gl_context.rs

// This file was generated by gir (https://github.com/gtk-rs/gir)
// from gir-files (https://github.com/gtk-rs/gir-files)
// DO NOT EDIT

use crate::{Display, Window};
use glib::translate::*;
use std::{fmt, mem, ptr};

glib::wrapper! {
    /// [`GLContext`][crate::GLContext] is an object representing the platform-specific
    /// OpenGL drawing context.
    ///
    /// `GdkGLContexts` are created for a [`Window`][crate::Window] using
    /// [`Window::create_gl_context()`][crate::Window::create_gl_context()], and the context will match
    /// the [`Visual`][crate::Visual] of the window.
    ///
    /// A [`GLContext`][crate::GLContext] is not tied to any particular normal framebuffer.
    /// For instance, it cannot draw to the [`Window`][crate::Window] back buffer. The GDK
    /// repaint system is in full control of the painting to that. Instead,
    /// you can create render buffers or textures and use `gdk_cairo_draw_from_gl()`
    /// in the draw function of your widget to draw them. Then GDK will handle
    /// the integration of your rendering with that of other widgets.
    ///
    /// Support for [`GLContext`][crate::GLContext] is platform-specific, context creation
    /// can fail, returning [`None`] context.
    ///
    /// A [`GLContext`][crate::GLContext] has to be made "current" in order to start using
    /// it, otherwise any OpenGL call will be ignored.
    ///
    /// ## Creating a new OpenGL context ##
    ///
    /// In order to create a new [`GLContext`][crate::GLContext] instance you need a
    /// [`Window`][crate::Window], which you typically get during the realize call
    /// of a widget.
    ///
    /// A [`GLContext`][crate::GLContext] is not realized until either [`make_current()`][Self::make_current()],
    /// or until it is realized using [`realize()`][Self::realize()]. It is possible to
    /// specify details of the GL context like the OpenGL version to be used, or
    /// whether the GL context should have extra state validation enabled after
    /// calling [`Window::create_gl_context()`][crate::Window::create_gl_context()] by calling [`realize()`][Self::realize()].
    /// If the realization fails you have the option to change the settings of the
    /// [`GLContext`][crate::GLContext] and try again.
    ///
    /// ## Using a GdkGLContext ##
    ///
    /// You will need to make the [`GLContext`][crate::GLContext] the current context
    /// before issuing OpenGL calls; the system sends OpenGL commands to
    /// whichever context is current. It is possible to have multiple
    /// contexts, so you always need to ensure that the one which you
    /// want to draw with is the current one before issuing commands:
    ///
    ///
    ///
    /// **⚠️ The following code is in C ⚠️**
    ///
    /// ```C
    ///   gdk_gl_context_make_current (context);
    /// ```
    ///
    /// You can now perform your drawing using OpenGL commands.
    ///
    /// You can check which [`GLContext`][crate::GLContext] is the current one by using
    /// [`current()`][Self::current()]; you can also unset any [`GLContext`][crate::GLContext]
    /// that is currently set by calling [`clear_current()`][Self::clear_current()].
    ///
    /// This is an Abstract Base Class, you cannot instantiate it.
    ///
    /// ## Properties
    ///
    ///
    /// #### `display`
    ///  The [`Display`][crate::Display] used to create the [`GLContext`][crate::GLContext].
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `shared-context`
    ///  The [`GLContext`][crate::GLContext] that this context is sharing data with, or [`None`]
    ///
    /// Readable | Writeable | Construct Only
    ///
    ///
    /// #### `window`
    ///  The [`Window`][crate::Window] the gl context is bound to.
    ///
    /// Readable | Writeable | Construct Only
    #[doc(alias = "GdkGLContext")]
    pub struct GLContext(Object<ffi::GdkGLContext>);

    match fn {
        type_ => || ffi::gdk_gl_context_get_type(),
    }
}

impl GLContext {
    /// Retrieves the value set using [`set_debug_enabled()`][Self::set_debug_enabled()].
    ///
    /// # Returns
    ///
    /// [`true`] if debugging is enabled
    #[doc(alias = "gdk_gl_context_get_debug_enabled")]
    #[doc(alias = "get_debug_enabled")]
    pub fn is_debug_enabled(&self) -> bool {
        unsafe { from_glib(ffi::gdk_gl_context_get_debug_enabled(self.to_glib_none().0)) }
    }

    /// Retrieves the [`Display`][crate::Display] the `self` is created for
    ///
    /// # Returns
    ///
    /// a [`Display`][crate::Display] or [`None`]
    #[doc(alias = "gdk_gl_context_get_display")]
    #[doc(alias = "get_display")]
    pub fn display(&self) -> Option<Display> {
        unsafe { from_glib_none(ffi::gdk_gl_context_get_display(self.to_glib_none().0)) }
    }

    /// Retrieves the value set using [`set_forward_compatible()`][Self::set_forward_compatible()].
    ///
    /// # Returns
    ///
    /// [`true`] if the context should be forward compatible
    #[doc(alias = "gdk_gl_context_get_forward_compatible")]
    #[doc(alias = "get_forward_compatible")]
    pub fn is_forward_compatible(&self) -> bool {
        unsafe {
            from_glib(ffi::gdk_gl_context_get_forward_compatible(
                self.to_glib_none().0,
            ))
        }
    }

    /// Retrieves the major and minor version requested by calling
    /// [`set_required_version()`][Self::set_required_version()].
    ///
    /// # Returns
    ///
    ///
    /// ## `major`
    /// return location for the major version to request
    ///
    /// ## `minor`
    /// return location for the minor version to request
    #[doc(alias = "gdk_gl_context_get_required_version")]
    #[doc(alias = "get_required_version")]
    pub fn required_version(&self) -> (i32, i32) {
        unsafe {
            let mut major = mem::MaybeUninit::uninit();
            let mut minor = mem::MaybeUninit::uninit();
            ffi::gdk_gl_context_get_required_version(
                self.to_glib_none().0,
                major.as_mut_ptr(),
                minor.as_mut_ptr(),
            );
            (major.assume_init(), minor.assume_init())
        }
    }

    /// Retrieves the [`GLContext`][crate::GLContext] that this `self` share data with.
    ///
    /// # Returns
    ///
    /// a [`GLContext`][crate::GLContext] or [`None`]
    #[doc(alias = "gdk_gl_context_get_shared_context")]
    #[doc(alias = "get_shared_context")]
    #[must_use]
    pub fn shared_context(&self) -> Option<GLContext> {
        unsafe {
            from_glib_none(ffi::gdk_gl_context_get_shared_context(
                self.to_glib_none().0,
            ))
        }
    }

    /// Checks whether the `self` is using an OpenGL or OpenGL ES profile.
    ///
    /// # Returns
    ///
    /// [`true`] if the [`GLContext`][crate::GLContext] is using an OpenGL ES profile
    #[doc(alias = "gdk_gl_context_get_use_es")]
    #[doc(alias = "get_use_es")]
    pub fn uses_es(&self) -> bool {
        unsafe { from_glib(ffi::gdk_gl_context_get_use_es(self.to_glib_none().0)) }
    }

    /// Retrieves the OpenGL version of the `self`.
    ///
    /// The `self` must be realized prior to calling this function.
    ///
    /// # Returns
    ///
    ///
    /// ## `major`
    /// return location for the major version
    ///
    /// ## `minor`
    /// return location for the minor version
    #[doc(alias = "gdk_gl_context_get_version")]
    #[doc(alias = "get_version")]
    pub fn version(&self) -> (i32, i32) {
        unsafe {
            let mut major = mem::MaybeUninit::uninit();
            let mut minor = mem::MaybeUninit::uninit();
            ffi::gdk_gl_context_get_version(
                self.to_glib_none().0,
                major.as_mut_ptr(),
                minor.as_mut_ptr(),
            );
            (major.assume_init(), minor.assume_init())
        }
    }

    /// Retrieves the [`Window`][crate::Window] used by the `self`.
    ///
    /// # Returns
    ///
    /// a [`Window`][crate::Window] or [`None`]
    #[doc(alias = "gdk_gl_context_get_window")]
    #[doc(alias = "get_window")]
    pub fn window(&self) -> Option<Window> {
        unsafe { from_glib_none(ffi::gdk_gl_context_get_window(self.to_glib_none().0)) }
    }

    /// Whether the [`GLContext`][crate::GLContext] is in legacy mode or not.
    ///
    /// The [`GLContext`][crate::GLContext] must be realized before calling this function.
    ///
    /// When realizing a GL context, GDK will try to use the OpenGL 3.2 core
    /// profile; this profile removes all the OpenGL API that was deprecated
    /// prior to the 3.2 version of the specification. If the realization is
    /// successful, this function will return [`false`].
    ///
    /// If the underlying OpenGL implementation does not support core profiles,
    /// GDK will fall back to a pre-3.2 compatibility profile, and this function
    /// will return [`true`].
    ///
    /// You can use the value returned by this function to decide which kind
    /// of OpenGL API to use, or whether to do extension discovery, or what
    /// kind of shader programs to load.
    ///
    /// # Returns
    ///
    /// [`true`] if the GL context is in legacy mode
    #[doc(alias = "gdk_gl_context_is_legacy")]
    pub fn is_legacy(&self) -> bool {
        unsafe { from_glib(ffi::gdk_gl_context_is_legacy(self.to_glib_none().0)) }
    }

    /// Makes the `self` the current one.
    #[doc(alias = "gdk_gl_context_make_current")]
    pub fn make_current(&self) {
        unsafe {
            ffi::gdk_gl_context_make_current(self.to_glib_none().0);
        }
    }

    /// Realizes the given [`GLContext`][crate::GLContext].
    ///
    /// It is safe to call this function on a realized [`GLContext`][crate::GLContext].
    ///
    /// # Returns
    ///
    /// [`true`] if the context is realized
    #[doc(alias = "gdk_gl_context_realize")]
    pub fn realize(&self) -> Result<(), glib::Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let is_ok = ffi::gdk_gl_context_realize(self.to_glib_none().0, &mut error);
            debug_assert_eq!(is_ok == glib::ffi::GFALSE, !error.is_null());
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Sets whether the [`GLContext`][crate::GLContext] should perform extra validations and
    /// run time checking. This is useful during development, but has
    /// additional overhead.
    ///
    /// The [`GLContext`][crate::GLContext] must not be realized or made current prior to
    /// calling this function.
    /// ## `enabled`
    /// whether to enable debugging in the context
    #[doc(alias = "gdk_gl_context_set_debug_enabled")]
    pub fn set_debug_enabled(&self, enabled: bool) {
        unsafe {
            ffi::gdk_gl_context_set_debug_enabled(self.to_glib_none().0, enabled.into_glib());
        }
    }

    /// Sets whether the [`GLContext`][crate::GLContext] should be forward compatible.
    ///
    /// Forward compatibile contexts must not support OpenGL functionality that
    /// has been marked as deprecated in the requested version; non-forward
    /// compatible contexts, on the other hand, must support both deprecated and
    /// non deprecated functionality.
    ///
    /// The [`GLContext`][crate::GLContext] must not be realized or made current prior to calling
    /// this function.
    /// ## `compatible`
    /// whether the context should be forward compatible
    #[doc(alias = "gdk_gl_context_set_forward_compatible")]
    pub fn set_forward_compatible(&self, compatible: bool) {
        unsafe {
            ffi::gdk_gl_context_set_forward_compatible(
                self.to_glib_none().0,
                compatible.into_glib(),
            );
        }
    }

    /// Sets the major and minor version of OpenGL to request.
    ///
    /// Setting `major` and `minor` to zero will use the default values.
    ///
    /// The [`GLContext`][crate::GLContext] must not be realized or made current prior to calling
    /// this function.
    /// ## `major`
    /// the major version to request
    /// ## `minor`
    /// the minor version to request
    #[doc(alias = "gdk_gl_context_set_required_version")]
    pub fn set_required_version(&self, major: i32, minor: i32) {
        unsafe {
            ffi::gdk_gl_context_set_required_version(self.to_glib_none().0, major, minor);
        }
    }

    /// Requests that GDK create a OpenGL ES context instead of an OpenGL one,
    /// if the platform and windowing system allows it.
    ///
    /// The `self` must not have been realized.
    ///
    /// By default, GDK will attempt to automatically detect whether the
    /// underlying GL implementation is OpenGL or OpenGL ES once the `self`
    /// is realized.
    ///
    /// You should check the return value of [`uses_es()`][Self::uses_es()] after
    /// calling [`realize()`][Self::realize()] to decide whether to use the OpenGL or
    /// OpenGL ES API, extensions, or shaders.
    /// ## `use_es`
    /// whether the context should use OpenGL ES instead of OpenGL,
    ///  or -1 to allow auto-detection
    #[doc(alias = "gdk_gl_context_set_use_es")]
    pub fn set_use_es(&self, use_es: i32) {
        unsafe {
            ffi::gdk_gl_context_set_use_es(self.to_glib_none().0, use_es);
        }
    }

    /// Clears the current [`GLContext`][crate::GLContext].
    ///
    /// Any OpenGL call after this function returns will be ignored
    /// until [`make_current()`][Self::make_current()] is called.
    #[doc(alias = "gdk_gl_context_clear_current")]
    pub fn clear_current() {
        assert_initialized_main_thread!();
        unsafe {
            ffi::gdk_gl_context_clear_current();
        }
    }

    /// Retrieves the current [`GLContext`][crate::GLContext].
    ///
    /// # Returns
    ///
    /// the current [`GLContext`][crate::GLContext], or [`None`]
    #[doc(alias = "gdk_gl_context_get_current")]
    #[doc(alias = "get_current")]
    pub fn current() -> Option<GLContext> {
        assert_initialized_main_thread!();
        unsafe { from_glib_none(ffi::gdk_gl_context_get_current()) }
    }
}

impl fmt::Display for GLContext {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        f.write_str("GLContext")
    }
}