aboutsummaryrefslogtreecommitdiffstats
path: root/src
diff options
context:
space:
mode:
Diffstat (limited to 'src')
-rw-r--r--src/lib.rs124
1 files changed, 119 insertions, 5 deletions
diff --git a/src/lib.rs b/src/lib.rs
index 1b90ad2..25cc9ad 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,5 +1,6 @@
#![feature(unsafe_destructor)]
#![feature(globs)]
+#![unstable]
extern crate libc;
@@ -26,7 +27,63 @@ pub struct Window {
nosend: std::kinds::marker::NoSend,
}
+/// Represents an OpenGL context and the Window or environment around it.
+///
+/// # Example
+///
+/// ```
+/// use std::default::Default;
+///
+/// let window = Window::new(None, "Hello world!", &Default::default(), None).unwrap();
+///
+/// window.make_current();
+///
+/// loop {
+/// for event in window.poll_events().move_iter() { // note: this may change in the future
+/// match event {
+/// // process events here
+/// _ => ()
+/// }
+/// }
+///
+/// // draw everything here
+///
+/// window.swap_buffers();
+/// std::io::timer::sleep(17);
+/// }
+///
+/// while !window.is_closed() {
+/// println!("{}", window.wait_events());
+///
+/// gl::Clear(gl::COLOR_BUFFER_BIT);
+///
+/// window.swap_buffers();
+/// }
impl Window {
+ /// Creates a new OpenGL context, and a Window for platforms where this is appropriate.
+ ///
+ /// # Parameters
+ ///
+ /// The `dimensions` parameter tell the library what the dimensions of the client area
+ /// of the window must be. If set to `None`, the library will choose or let the O/S choose.
+ ///
+ /// The `title` parameter is the title that the window must have.
+ ///
+ /// The `hints` parameter must be a `Hint` object which contains hints about how the context
+ /// must be created. This library will *try* to follow the hints, but will still success
+ /// even if it could not conform to all of them.
+ ///
+ /// The `monitor` parameter is the identifier of the monitor that this window should fill.
+ /// If `None`, a windowed window will be created. If `Some(_)`, the window will be fullscreen
+ /// and will fill the given monitor. Note `MonitorID` does not necessarly represent a
+ /// *physical* monitor.
+ ///
+ /// # Return value
+ ///
+ /// Returns the `Window` object.
+ ///
+ /// Error should be very rare and only occur in case of permission denied, incompatible system,
+ /// out of memory, etc.
#[inline]
pub fn new(dimensions: Option<(uint, uint)>, title: &str,
hints: &Hints, monitor: Option<MonitorID>)
@@ -39,13 +96,13 @@ impl Window {
})
}
- /// Returns true if the window has been closed by the user.
+ /// Returns true if the window has previously been closed by the user.
#[inline]
pub fn is_closed(&self) -> bool {
self.window.is_closed()
}
- /// Returns true if the window has been closed by the user.
+ /// Returns true if the window has previously been closed by the user.
#[inline]
#[deprecated = "Use is_closed instead"]
pub fn should_close(&self) -> bool {
@@ -53,12 +110,22 @@ impl Window {
}
/// Modifies the title of the window.
+ ///
+ /// This is a no-op if the window has already been closed.
#[inline]
pub fn set_title(&self, title: &str) {
self.window.set_title(title)
}
- /// Returns the position of the window relative to the top-left hand corner of the screen.
+ /// Returns the position of the top-left hand corner of the window relative to the
+ /// top-left hand corner of the desktop.
+ ///
+ /// Note that the top-left hand corner of the desktop is not necessarly the same as
+ /// the screen. If the user uses a desktop with multiple monitors, the top-left hand corner
+ /// of the desktop is the top-left hand corner of the monitor at the top-left of the desktop.
+ ///
+ /// The coordinates can be negative if the top-left hand corner of the window is outside
+ /// of the visible screen region.
///
/// Returns `None` if the window no longer exists.
#[inline]
@@ -66,48 +133,95 @@ impl Window {
self.window.get_position()
}
+ /// Modifies the position of the window.
+ ///
+ /// See `get_position` for more informations about the coordinates.
+ ///
+ /// This is a no-op if the window has already been closed.
#[inline]
pub fn set_position(&self, x: uint, y: uint) {
self.window.set_position(x, y)
}
+ /// Returns the size in pixels of the client area of the window.
+ ///
+ /// The client area is the content of the window, excluding the title bar and borders.
+ /// These are the dimensions of the frame buffer, and the dimensions that you should use
+ /// when you call `glViewport`.
+ ///
+ /// Returns `None` if the window no longer exists.
#[inline]
pub fn get_inner_size(&self) -> Option<(uint, uint)> {
self.window.get_inner_size()
}
+ /// Returns the size in pixels of the window.
+ ///
+ /// These dimensions include title bar and borders. If you don't want these, you should use
+ /// use `get_inner_size` instead.
+ ///
+ /// Returns `None` if the window no longer exists.
#[inline]
pub fn get_outer_size(&self) -> Option<(uint, uint)> {
self.window.get_outer_size()
}
+ /// Modifies the inner size of the window.
+ ///
+ /// See `get_inner_size` for more informations about the values.
+ ///
+ /// This is a no-op if the window has already been closed.
#[inline]
pub fn set_inner_size(&self, x: uint, y: uint) {
self.window.set_inner_size(x, y)
}
- // TODO: return iterator
+ /// Returns all the events that are currently in window's events queue.
+ ///
+ /// Contrary to `wait_events`, this function never blocks.
+ #[experimental = "Will probably be changed to return an iterator instead of a Vec"]
#[inline]
pub fn poll_events(&self) -> Vec<Event> {
self.window.poll_events()
}
- // TODO: return iterator
+ /// Returns all the events that are currently in window's events queue.
+ /// If there are no events in queue, this function will block until there is one.
+ ///
+ /// This is equivalent to:
+ ///
+ /// ```
+ /// loop {
+ /// let events = poll_events();
+ /// if events.len() >= 1 { return events }
+ /// }
+ /// ```
+ ///
+ /// ...but without the spinlock.
#[inline]
+ #[experimental = "Will probably be changed to return an iterator instead of a Vec"]
pub fn wait_events(&self) -> Vec<Event> {
self.window.wait_events()
}
#[inline]
+ #[experimental]
pub fn make_current(&self) {
self.window.make_current()
}
+ /// Returns the address of an OpenGL function.
+ ///
+ /// Contrary to `wglGetProcAddress`, all available OpenGL functions return an address.
#[inline]
pub fn get_proc_address(&self, addr: &str) -> *const () {
self.window.get_proc_address(addr)
}
+ /// Swaps the buffers in case of double or triple buffering.
+ ///
+ /// You should call this function every time you have finished rendering, or the image
+ /// may not be displayed on the screen.
#[inline]
pub fn swap_buffers(&self) {
self.window.swap_buffers()