2014-08-03 04:49:48 +10:00
|
|
|
//! The purpose of this library is to provide an OpenGL context on as many
|
|
|
|
//! platforms as possible.
|
|
|
|
//!
|
|
|
|
//! # Building a window
|
2014-09-04 19:38:33 +10:00
|
|
|
//!
|
2014-08-03 04:49:48 +10:00
|
|
|
//! There are two ways to create a window:
|
2014-09-04 19:38:33 +10:00
|
|
|
//!
|
2014-08-03 04:49:48 +10:00
|
|
|
//! - Calling `Window::new()`.
|
|
|
|
//! - Calling `let builder = WindowBuilder::new()` then `builder.build()`.
|
|
|
|
//!
|
|
|
|
//! The first way is the simpliest way and will give you default values.
|
|
|
|
//!
|
|
|
|
//! The second way allows you to customize the way your window and GL context
|
|
|
|
//! will look and behave.
|
2014-10-05 04:17:02 +11:00
|
|
|
//!
|
|
|
|
//! # Features
|
|
|
|
//!
|
|
|
|
//! This crate has two Cargo features: `window` and `headless`.
|
|
|
|
//!
|
|
|
|
//! - `window` allows you to create regular windows and enables the `WindowBuilder` object.
|
|
|
|
//! - `headless` allows you to do headless rendering, and enables
|
|
|
|
//! the `HeadlessRendererBuilder` object.
|
|
|
|
//!
|
|
|
|
//! By default only `window` is enabled.
|
2014-08-03 04:49:48 +10:00
|
|
|
|
2015-04-03 17:33:51 +11:00
|
|
|
#[macro_use]
|
|
|
|
extern crate lazy_static;
|
|
|
|
|
2015-04-27 22:25:53 +10:00
|
|
|
#[macro_use]
|
|
|
|
extern crate shared_library;
|
|
|
|
|
2014-11-06 01:22:21 +11:00
|
|
|
extern crate gl_common;
|
2014-07-27 18:55:37 +10:00
|
|
|
extern crate libc;
|
|
|
|
|
2014-12-02 04:24:15 +11:00
|
|
|
#[cfg(target_os = "windows")]
|
|
|
|
extern crate winapi;
|
2015-01-26 13:52:17 +11:00
|
|
|
#[cfg(target_os = "windows")]
|
2015-03-28 21:07:41 +11:00
|
|
|
extern crate kernel32;
|
2015-01-26 13:52:17 +11:00
|
|
|
#[cfg(target_os = "windows")]
|
2015-03-30 14:58:13 +11:00
|
|
|
extern crate gdi32;
|
2015-01-26 13:52:17 +11:00
|
|
|
#[cfg(target_os = "windows")]
|
2015-03-30 14:58:13 +11:00
|
|
|
extern crate user32;
|
2014-10-04 23:49:39 +10:00
|
|
|
#[cfg(target_os = "macos")]
|
2015-03-22 16:31:32 +11:00
|
|
|
#[macro_use]
|
|
|
|
extern crate objc;
|
|
|
|
#[cfg(target_os = "macos")]
|
2014-10-04 23:49:39 +10:00
|
|
|
extern crate cocoa;
|
|
|
|
#[cfg(target_os = "macos")]
|
|
|
|
extern crate core_foundation;
|
2014-11-05 04:03:38 +11:00
|
|
|
#[cfg(target_os = "macos")]
|
2015-03-26 05:57:38 +11:00
|
|
|
extern crate glutin_core_graphics as core_graphics;
|
2015-04-12 11:17:49 +10:00
|
|
|
#[cfg(any(target_os = "linux", target_os = "freebsd"))]
|
2015-04-09 20:38:58 +10:00
|
|
|
extern crate x11;
|
2014-10-04 23:49:39 +10:00
|
|
|
|
2014-07-30 21:11:49 +10:00
|
|
|
pub use events::*;
|
2015-02-16 19:29:37 +11:00
|
|
|
#[cfg(feature = "headless")]
|
|
|
|
pub use headless::{HeadlessRendererBuilder, HeadlessContext};
|
|
|
|
#[cfg(feature = "window")]
|
|
|
|
pub use window::{WindowBuilder, Window, WindowProxy, PollEventsIterator, WaitEventsIterator};
|
|
|
|
#[cfg(feature = "window")]
|
|
|
|
pub use window::{AvailableMonitorsIter, MonitorID, get_available_monitors, get_primary_monitor};
|
2015-03-19 08:16:35 +11:00
|
|
|
#[cfg(feature = "window")]
|
|
|
|
pub use native_monitor::NativeMonitorId;
|
2014-08-13 22:52:12 +10:00
|
|
|
|
2015-04-24 17:51:23 +10:00
|
|
|
mod api;
|
2015-04-02 17:27:32 +11:00
|
|
|
mod platform;
|
2014-07-27 20:59:45 +10:00
|
|
|
mod events;
|
2015-02-16 19:29:37 +11:00
|
|
|
#[cfg(feature = "headless")]
|
|
|
|
mod headless;
|
2014-10-05 04:17:02 +11:00
|
|
|
#[cfg(feature = "window")]
|
2015-02-16 19:29:37 +11:00
|
|
|
mod window;
|
2014-07-28 04:38:27 +10:00
|
|
|
|
2014-11-06 02:42:18 +11:00
|
|
|
/// Error that can happen while creating a window or a headless renderer.
|
2015-01-24 12:50:06 +11:00
|
|
|
#[derive(Clone, Debug, PartialEq, Eq)]
|
2014-11-06 02:42:18 +11:00
|
|
|
pub enum CreationError {
|
|
|
|
OsError(String),
|
2014-12-29 01:53:24 +11:00
|
|
|
NotSupported,
|
2014-11-06 02:42:18 +11:00
|
|
|
}
|
|
|
|
|
2015-01-24 12:50:06 +11:00
|
|
|
impl CreationError {
|
|
|
|
fn to_string(&self) -> &str {
|
2015-02-22 10:07:35 +11:00
|
|
|
match *self {
|
2015-03-26 05:57:38 +11:00
|
|
|
CreationError::OsError(ref text) => &text,
|
2015-02-22 10:07:35 +11:00
|
|
|
CreationError::NotSupported => "Some of the requested attributes are not supported",
|
2014-11-06 02:42:18 +11:00
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2015-01-24 12:50:06 +11:00
|
|
|
impl std::fmt::Display for CreationError {
|
|
|
|
fn fmt(&self, formatter: &mut std::fmt::Formatter) -> Result<(), std::fmt::Error> {
|
|
|
|
formatter.write_str(self.to_string())
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
impl std::error::Error for CreationError {
|
|
|
|
fn description(&self) -> &str {
|
|
|
|
self.to_string()
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2014-11-19 03:55:26 +11:00
|
|
|
/// All APIs related to OpenGL that you can possibly get while using glutin.
|
2015-01-24 12:50:06 +11:00
|
|
|
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
|
2014-11-19 03:55:26 +11:00
|
|
|
pub enum Api {
|
|
|
|
/// The classical OpenGL. Available on Windows, Linux, OS/X.
|
|
|
|
OpenGl,
|
|
|
|
/// OpenGL embedded system. Available on Linux, Android.
|
|
|
|
OpenGlEs,
|
2015-01-30 04:36:03 +11:00
|
|
|
/// OpenGL for the web. Very similar to OpenGL ES.
|
|
|
|
WebGl,
|
2014-11-19 03:55:26 +11:00
|
|
|
}
|
|
|
|
|
2015-02-19 02:49:53 +11:00
|
|
|
/// Describes the OpenGL API and version that are being requested when a context is created.
|
|
|
|
#[derive(Debug, Copy, Clone)]
|
|
|
|
pub enum GlRequest {
|
|
|
|
/// Request the latest version of the "best" API of this platform.
|
|
|
|
///
|
|
|
|
/// On desktop, will try OpenGL.
|
|
|
|
Latest,
|
|
|
|
|
|
|
|
/// Request a specific version of a specific API.
|
|
|
|
///
|
|
|
|
/// Example: `GlRequest::Specific(Api::OpenGl, (3, 3))`.
|
|
|
|
Specific(Api, (u8, u8)),
|
|
|
|
|
|
|
|
/// If OpenGL is available, create an OpenGL context with the specified `opengl_version`.
|
|
|
|
/// Else if OpenGL ES or WebGL is available, create a context with the
|
|
|
|
/// specified `opengles_version`.
|
|
|
|
GlThenGles {
|
|
|
|
/// The version to use for OpenGL.
|
|
|
|
opengl_version: (u8, u8),
|
|
|
|
/// The version to use for OpenGL ES.
|
|
|
|
opengles_version: (u8, u8),
|
|
|
|
},
|
|
|
|
}
|
|
|
|
|
2015-04-04 03:36:57 +11:00
|
|
|
#[derive(Debug, Copy, Clone)]
|
2015-01-13 11:22:37 +11:00
|
|
|
pub enum MouseCursor {
|
|
|
|
/// The platform-dependent default cursor.
|
|
|
|
Default,
|
|
|
|
/// A simple crosshair.
|
|
|
|
Crosshair,
|
|
|
|
/// A hand (often used to indicate links in web browsers).
|
|
|
|
Hand,
|
|
|
|
/// Self explanatory.
|
|
|
|
Arrow,
|
|
|
|
/// Indicates something is to be moved.
|
|
|
|
Move,
|
|
|
|
/// Indicates text that may be selected or edited.
|
|
|
|
Text,
|
|
|
|
/// Program busy indicator.
|
|
|
|
Wait,
|
|
|
|
/// Help indicator (often rendered as a "?")
|
|
|
|
Help,
|
|
|
|
/// Progress indicator. Shows that processing is being done. But in contrast
|
|
|
|
/// with "Wait" the user may still interact with the program. Often rendered
|
2015-01-26 14:28:12 +11:00
|
|
|
/// as a spinning beach ball, or an arrow with a watch or hourglass.
|
2015-01-13 11:22:37 +11:00
|
|
|
Progress,
|
|
|
|
|
|
|
|
/// Cursor showing that something cannot be done.
|
|
|
|
NotAllowed,
|
|
|
|
ContextMenu,
|
|
|
|
NoneCursor,
|
|
|
|
Cell,
|
|
|
|
VerticalText,
|
|
|
|
Alias,
|
|
|
|
Copy,
|
|
|
|
NoDrop,
|
|
|
|
Grab,
|
|
|
|
Grabbing,
|
|
|
|
AllScroll,
|
|
|
|
ZoomIn,
|
|
|
|
ZoomOut,
|
|
|
|
|
|
|
|
/// Indicate that some edge is to be moved. For example, the 'SeResize' cursor
|
|
|
|
/// is used when the movement starts from the south-east corner of the box.
|
|
|
|
EResize,
|
|
|
|
NResize,
|
|
|
|
NeResize,
|
|
|
|
NwResize,
|
|
|
|
SResize,
|
|
|
|
SeResize,
|
|
|
|
SwResize,
|
|
|
|
WResize,
|
|
|
|
EwResize,
|
|
|
|
NsResize,
|
|
|
|
NeswResize,
|
|
|
|
NwseResize,
|
|
|
|
ColResize,
|
|
|
|
RowResize,
|
|
|
|
}
|
|
|
|
|
2015-03-27 03:04:01 +11:00
|
|
|
/// Describes how glutin handles the cursor.
|
2015-04-04 03:36:57 +11:00
|
|
|
#[derive(Debug, Copy, Clone)]
|
2015-03-27 03:04:01 +11:00
|
|
|
pub enum CursorState {
|
|
|
|
/// Normal cursor behavior.
|
|
|
|
Normal,
|
|
|
|
|
|
|
|
/// The cursor will be invisible when over the window.
|
|
|
|
Hide,
|
|
|
|
|
|
|
|
/// Grabs the mouse cursor. The cursor's motion will be confined to this
|
|
|
|
/// window and the window has exclusive access to further events regarding
|
|
|
|
/// the cursor.
|
|
|
|
///
|
|
|
|
/// This is useful for first-person cameras for example.
|
|
|
|
Grab,
|
|
|
|
}
|
|
|
|
|
2015-02-17 01:36:32 +11:00
|
|
|
/// Describes a possible format. Unused.
|
|
|
|
#[allow(missing_docs)]
|
2015-03-01 21:46:58 +11:00
|
|
|
#[derive(Debug, Clone)]
|
2015-02-17 01:36:32 +11:00
|
|
|
pub struct PixelFormat {
|
2015-03-01 21:07:46 +11:00
|
|
|
pub hardware_accelerated: bool,
|
2015-02-17 01:36:32 +11:00
|
|
|
pub red_bits: u8,
|
|
|
|
pub green_bits: u8,
|
|
|
|
pub blue_bits: u8,
|
|
|
|
pub alpha_bits: u8,
|
|
|
|
pub depth_bits: u8,
|
|
|
|
pub stencil_bits: u8,
|
|
|
|
pub stereoscopy: bool,
|
|
|
|
pub double_buffer: bool,
|
|
|
|
pub multisampling: Option<u16>,
|
|
|
|
pub srgb: bool,
|
|
|
|
}
|
|
|
|
|
2015-01-02 18:09:16 +11:00
|
|
|
/// Attributes
|
2015-03-21 23:43:14 +11:00
|
|
|
// FIXME: remove `pub` (https://github.com/rust-lang/rust/issues/23585)
|
|
|
|
#[doc(hidden)]
|
|
|
|
pub struct BuilderAttribs<'a> {
|
2015-01-23 19:15:18 +11:00
|
|
|
#[allow(dead_code)]
|
2014-12-29 01:08:41 +11:00
|
|
|
headless: bool,
|
|
|
|
strict: bool,
|
2015-04-02 17:27:32 +11:00
|
|
|
sharing: Option<&'a platform::Window>,
|
2015-01-13 23:21:36 +11:00
|
|
|
dimensions: Option<(u32, u32)>,
|
2014-08-02 16:24:30 +10:00
|
|
|
title: String,
|
2015-04-02 17:27:32 +11:00
|
|
|
monitor: Option<platform::MonitorID>,
|
2015-02-19 02:49:53 +11:00
|
|
|
gl_version: GlRequest,
|
2014-11-10 02:07:58 +11:00
|
|
|
gl_debug: bool,
|
2014-10-26 20:32:51 +11:00
|
|
|
vsync: bool,
|
2014-11-01 19:02:01 +11:00
|
|
|
visible: bool,
|
2014-11-25 05:35:31 +11:00
|
|
|
multisampling: Option<u16>,
|
2014-12-29 02:09:28 +11:00
|
|
|
depth_bits: Option<u8>,
|
|
|
|
stencil_bits: Option<u8>,
|
|
|
|
color_bits: Option<u8>,
|
|
|
|
alpha_bits: Option<u8>,
|
|
|
|
stereoscopy: bool,
|
2015-04-03 23:02:33 +11:00
|
|
|
srgb: Option<bool>,
|
2014-08-02 16:24:30 +10:00
|
|
|
}
|
|
|
|
|
2014-12-29 01:08:41 +11:00
|
|
|
impl BuilderAttribs<'static> {
|
|
|
|
fn new() -> BuilderAttribs<'static> {
|
|
|
|
BuilderAttribs {
|
|
|
|
headless: false,
|
|
|
|
strict: false,
|
2014-11-25 06:13:32 +11:00
|
|
|
sharing: None,
|
2014-08-02 19:23:32 +10:00
|
|
|
dimensions: None,
|
2014-10-27 23:10:10 +11:00
|
|
|
title: "glutin window".to_string(),
|
2014-08-02 16:24:30 +10:00
|
|
|
monitor: None,
|
2015-02-19 02:49:53 +11:00
|
|
|
gl_version: GlRequest::Latest,
|
2015-04-02 19:13:01 +11:00
|
|
|
gl_debug: cfg!(debug_assertions),
|
2014-10-26 20:32:51 +11:00
|
|
|
vsync: false,
|
2014-11-01 19:02:01 +11:00
|
|
|
visible: true,
|
2014-11-25 05:35:31 +11:00
|
|
|
multisampling: None,
|
2014-12-29 02:09:28 +11:00
|
|
|
depth_bits: None,
|
|
|
|
stencil_bits: None,
|
|
|
|
color_bits: None,
|
|
|
|
alpha_bits: None,
|
|
|
|
stereoscopy: false,
|
2015-04-03 23:02:33 +11:00
|
|
|
srgb: None,
|
2014-08-02 16:24:30 +10:00
|
|
|
}
|
|
|
|
}
|
2014-12-29 01:08:41 +11:00
|
|
|
}
|
|
|
|
|
2015-01-14 20:04:28 +11:00
|
|
|
impl<'a> BuilderAttribs<'a> {
|
2015-04-02 17:27:32 +11:00
|
|
|
fn extract_non_static(mut self) -> (BuilderAttribs<'static>, Option<&'a platform::Window>) {
|
2015-01-14 20:04:28 +11:00
|
|
|
let sharing = self.sharing.take();
|
|
|
|
|
|
|
|
let new_attribs = BuilderAttribs {
|
|
|
|
headless: self.headless,
|
|
|
|
strict: self.strict,
|
|
|
|
sharing: None,
|
|
|
|
dimensions: self.dimensions,
|
|
|
|
title: self.title,
|
|
|
|
monitor: self.monitor,
|
|
|
|
gl_version: self.gl_version,
|
|
|
|
gl_debug: self.gl_debug,
|
|
|
|
vsync: self.vsync,
|
|
|
|
visible: self.visible,
|
|
|
|
multisampling: self.multisampling,
|
|
|
|
depth_bits: self.depth_bits,
|
|
|
|
stencil_bits: self.stencil_bits,
|
|
|
|
color_bits: self.color_bits,
|
|
|
|
alpha_bits: self.alpha_bits,
|
|
|
|
stereoscopy: self.stereoscopy,
|
2015-04-03 23:02:33 +11:00
|
|
|
srgb: self.srgb,
|
2015-01-14 20:04:28 +11:00
|
|
|
};
|
|
|
|
|
|
|
|
(new_attribs, sharing)
|
|
|
|
}
|
|
|
|
|
2015-03-27 05:07:59 +11:00
|
|
|
fn choose_pixel_format<T, I>(&self, iter: I) -> Result<(T, PixelFormat), CreationError>
|
2015-02-17 01:36:32 +11:00
|
|
|
where I: Iterator<Item=(T, PixelFormat)>, T: Clone
|
|
|
|
{
|
|
|
|
let mut current_result = None;
|
2015-03-01 21:46:58 +11:00
|
|
|
let mut current_software_result = None;
|
2015-02-17 01:36:32 +11:00
|
|
|
|
|
|
|
// TODO: do this more properly
|
|
|
|
for (id, format) in iter {
|
|
|
|
if format.red_bits + format.green_bits + format.blue_bits < self.color_bits.unwrap_or(0) {
|
|
|
|
continue;
|
|
|
|
}
|
|
|
|
|
|
|
|
if format.alpha_bits < self.alpha_bits.unwrap_or(0) {
|
|
|
|
continue;
|
|
|
|
}
|
|
|
|
|
|
|
|
if format.depth_bits < self.depth_bits.unwrap_or(0) {
|
|
|
|
continue;
|
|
|
|
}
|
|
|
|
|
|
|
|
if format.stencil_bits < self.stencil_bits.unwrap_or(0) {
|
|
|
|
continue;
|
|
|
|
}
|
|
|
|
|
|
|
|
if !format.stereoscopy && self.stereoscopy {
|
|
|
|
continue;
|
|
|
|
}
|
|
|
|
|
2015-04-03 23:02:33 +11:00
|
|
|
if self.multisampling.is_some() && format.multisampling.is_none() {
|
|
|
|
continue;
|
|
|
|
}
|
|
|
|
|
|
|
|
if let Some(srgb) = self.srgb {
|
|
|
|
if srgb != format.srgb {
|
|
|
|
continue;
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2015-03-01 21:46:58 +11:00
|
|
|
current_software_result = Some((id.clone(), format.clone()));
|
|
|
|
if format.hardware_accelerated {
|
|
|
|
current_result = Some((id, format));
|
|
|
|
}
|
2015-02-17 01:36:32 +11:00
|
|
|
}
|
|
|
|
|
2015-03-01 21:46:58 +11:00
|
|
|
current_result.or(current_software_result)
|
2015-03-27 05:07:59 +11:00
|
|
|
.ok_or(CreationError::NotSupported)
|
2015-02-17 01:36:32 +11:00
|
|
|
}
|
|
|
|
}
|
2015-03-19 08:16:35 +11:00
|
|
|
|
|
|
|
mod native_monitor {
|
|
|
|
/// Native platform identifier for a monitor. Different platforms use fundamentally different types
|
|
|
|
/// to represent a monitor ID.
|
|
|
|
#[derive(PartialEq, Eq)]
|
|
|
|
pub enum NativeMonitorId {
|
|
|
|
/// Cocoa and X11 use a numeric identifier to represent a monitor.
|
|
|
|
Numeric(u32),
|
|
|
|
|
|
|
|
/// Win32 uses a Unicode string to represent a monitor.
|
|
|
|
Name(String),
|
|
|
|
|
|
|
|
/// Other platforms (Android) don't support monitor identification.
|
|
|
|
Unavailable
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|