Add documentation to the Win32 implementation

This commit is contained in:
Tomaka17 2014-08-01 23:02:26 +02:00
parent 19b8474c4a
commit d93cea808d
3 changed files with 103 additions and 25 deletions

View file

@ -8,8 +8,10 @@ use super::{event, ffi};
use super::{MonitorID, Window};
use {Event, Hints};
/// Stores the list of all the windows.
/// Only available on callback thread.
/// Stores the current window and its events dispatcher.
///
/// We only have one window per thread. We still store the HWND in case where we
/// receive an event for another window.
local_data_key!(WINDOW: (ffi::HWND, Sender<Event>))
pub fn new_window(dimensions: Option<(uint, uint)>, title: &str,
@ -19,11 +21,14 @@ pub fn new_window(dimensions: Option<(uint, uint)>, title: &str,
use std::mem;
use std::os;
let title = title.to_string();
// initializing variables to be sent to the task
let title = title.utf16_units().collect::<Vec<u16>>().append_one(0); // title to utf16
//let hints = hints.clone();
let (tx, rx) = channel();
// GetMessage must be called in the same thread as CreateWindow,
// so we create a new thread dedicated to this window.
// This is the only safe method. Using `nosend` wouldn't work for non-native runtime.
TaskBuilder::new().native().spawn(proc() {
// registering the window class
let class_name: Vec<u16> = "Window Class".utf16_units().collect::<Vec<u16>>()
@ -57,7 +62,9 @@ pub fn new_window(dimensions: Option<(uint, uint)>, title: &str,
top: 0, bottom: dimensions.map(|(_, h)| h as ffi::LONG).unwrap_or(768),
};
// switching to fullscreen
// switching to fullscreen if necessary
// this means adjusting the window's position so that it overlaps the right monitor,
// and change the monitor's resolution if necessary
if monitor.is_some() {
let monitor = monitor.as_ref().unwrap();
@ -86,7 +93,7 @@ pub fn new_window(dimensions: Option<(uint, uint)>, title: &str,
}
}
// computing the style and extended style
// computing the style and extended style of the window
let (ex_style, style) = if monitor.is_some() {
(ffi::WS_EX_APPWINDOW, ffi::WS_POPUP | ffi::WS_CLIPSIBLINGS | ffi::WS_CLIPCHILDREN)
} else {
@ -94,13 +101,13 @@ pub fn new_window(dimensions: Option<(uint, uint)>, title: &str,
ffi::WS_OVERLAPPEDWINDOW | ffi::WS_CLIPSIBLINGS | ffi::WS_CLIPCHILDREN)
};
// adjusting
// adjusting the window coordinates using the style
unsafe { ffi::AdjustWindowRectEx(&mut rect, style, 0, ex_style) };
// creating the window
let handle = unsafe {
let handle = ffi::CreateWindowExW(ex_style, class_name.as_ptr(),
title.as_slice().utf16_units().collect::<Vec<u16>>().append_one(0).as_ptr() as ffi::LPCWSTR,
title.as_ptr() as ffi::LPCWSTR,
style | ffi::WS_VISIBLE | ffi::WS_CLIPSIBLINGS | ffi::WS_CLIPCHILDREN,
if monitor.is_some() { 0 } else { ffi::CW_USEDEFAULT},
if monitor.is_some() { 0 } else { ffi::CW_USEDEFAULT},
@ -123,7 +130,7 @@ pub fn new_window(dimensions: Option<(uint, uint)>, title: &str,
unsafe { ffi::SetForegroundWindow(handle) };
}
// adding it to WINDOWS_LIST
// filling the WINDOW task-local storage
let events_receiver = {
let (tx, rx) = channel();
WINDOW.replace(Some((handle, tx)));
@ -166,7 +173,7 @@ pub fn new_window(dimensions: Option<(uint, uint)>, title: &str,
}
}
// creating the context
// creating the OpenGL context
let context = {
let ctxt = unsafe { ffi::wglCreateContext(hdc) };
if ctxt.is_null() {
@ -177,7 +184,7 @@ pub fn new_window(dimensions: Option<(uint, uint)>, title: &str,
ctxt
};
// loading opengl32
// loading the opengl32 module
let gl_library = {
let name = "opengl32.dll".utf16_units().collect::<Vec<u16>>().append_one(0).as_ptr();
let lib = unsafe { ffi::LoadLibraryW(name) };
@ -199,22 +206,24 @@ pub fn new_window(dimensions: Option<(uint, uint)>, title: &str,
is_closed: AtomicBool::new(false),
}));
// starting the events loop
// now that the `Window` struct is initialized, the main `Window::new()` function will
// return and this events loop will run in parallel
loop {
let mut msg = unsafe { mem::uninitialized() };
if unsafe { ffi::GetMessageW(&mut msg, ptr::mut_null(), 0, 0) } == 0 {
break
break;
}
unsafe { ffi::TranslateMessage(&msg) };
unsafe { ffi::DispatchMessageW(&msg) };
unsafe { ffi::DispatchMessageW(&msg) }; // calls `callback` (see below)
}
});
rx.recv()
}
/// Checks that the window is the good one, and if so send the event to it.
fn send_event(window: ffi::HWND, event: Event) {
let stored = match WINDOW.get() {
None => return,
@ -230,6 +239,9 @@ fn send_event(window: ffi::HWND, event: Event) {
sender.send_opt(event).ok(); // ignoring if closed
}
/// This is the callback that is called by `DispatchMessage` in the events loop.
///
/// Returning 0 tells the Win32 API that the message has been processed.
extern "stdcall" fn callback(window: ffi::HWND, msg: ffi::UINT,
wparam: ffi::WPARAM, lparam: ffi::LPARAM) -> ffi::LRESULT
{

View file

@ -9,16 +9,32 @@ mod ffi;
mod init;
mod monitor;
/// The Win32 implementation of the main `Window` object.
pub struct Window {
/// Main handle for the window.
window: ffi::HWND,
/// This represents a "draw context" for the surface of the window.
hdc: ffi::HDC,
/// OpenGL context.
context: ffi::HGLRC,
/// Binded to `opengl32.dll`.
///
/// `wglGetProcAddress` returns null for GL 1.1 functions because they are
/// already defined by the system. This module contains them.
gl_library: ffi::HMODULE,
/// Receiver for the events dispatched by the window callback.
events_receiver: Receiver<Event>,
/// True if a `Closed` event has been received.
is_closed: AtomicBool,
}
impl Window {
/// See the docs if the crate root file.
pub fn new(dimensions: Option<(uint, uint)>, title: &str,
hints: &Hints, monitor: Option<MonitorID>)
-> Result<Window, String>
@ -26,11 +42,14 @@ impl Window {
init::new_window(dimensions, title, hints, monitor)
}
/// See the docs if the crate root file.
pub fn is_closed(&self) -> bool {
use std::sync::atomics::Relaxed;
self.is_closed.load(Relaxed)
}
/// See the docs if the crate root file.
///
/// Calls SetWindowText on the HWND.
pub fn set_title(&self, text: &str) {
unsafe {
@ -39,6 +58,7 @@ impl Window {
}
}
/// See the docs if the crate root file.
pub fn get_position(&self) -> Option<(int, int)> {
use std::mem;
@ -53,6 +73,7 @@ impl Window {
Some((rect.left as int, rect.top as int))
}
/// See the docs if the crate root file.
pub fn set_position(&self, x: uint, y: uint) {
use libc;
@ -63,6 +84,7 @@ impl Window {
}
}
/// See the docs if the crate root file.
pub fn get_inner_size(&self) -> Option<(uint, uint)> {
use std::mem;
let mut rect: ffi::RECT = unsafe { mem::uninitialized() };
@ -77,6 +99,7 @@ impl Window {
))
}
/// See the docs if the crate root file.
pub fn get_outer_size(&self) -> Option<(uint, uint)> {
use std::mem;
let mut rect: ffi::RECT = unsafe { mem::uninitialized() };
@ -91,6 +114,7 @@ impl Window {
))
}
/// See the docs if the crate root file.
pub fn set_inner_size(&self, x: uint, y: uint) {
use libc;
@ -101,6 +125,7 @@ impl Window {
}
}
/// See the docs if the crate root file.
// TODO: return iterator
pub fn poll_events(&self) -> Vec<Event> {
let mut events = Vec::new();
@ -119,6 +144,7 @@ impl Window {
events
}
/// See the docs if the crate root file.
// TODO: return iterator
pub fn wait_events(&self) -> Vec<Event> {
match self.events_receiver.recv_opt() {
@ -135,10 +161,12 @@ impl Window {
}
}
/// See the docs if the crate root file.
pub unsafe fn make_current(&self) {
ffi::wglMakeCurrent(self.hdc, self.context)
}
/// See the docs if the crate root file.
pub fn get_proc_address(&self, addr: &str) -> *const () {
use std::c_str::ToCStr;
@ -151,6 +179,7 @@ impl Window {
}
}
/// See the docs if the crate root file.
pub fn swap_buffers(&self) {
unsafe {
ffi::SwapBuffers(self.hdc);

View file

@ -1,34 +1,61 @@
use super::ffi;
/// Win32 implementation of the main `MonitorID` object.
pub struct MonitorID {
/// The system name of the monitor.
name: [ffi::WCHAR, ..32],
/// Name to give to the user.
readable_name: String,
/// See the `StateFlags` element here:
/// http://msdn.microsoft.com/en-us/library/dd183569(v=vs.85).aspx
flags: ffi::DWORD,
/// The position of the monitor in pixels on the desktop.
///
/// A window that is positionned at these coordinates will overlap the monitor.
position: (uint, uint),
}
/// Win32 implementation of the main `get_available_monitors` function.
pub fn get_available_monitors() -> Vec<MonitorID> {
use std::{iter, mem, ptr};
// return value
let mut result = Vec::new();
// enumerating the devices is done by querying device 0, then device 1, then device 2, etc.
// until the query function returns null
for id in iter::count(0u, 1) {
let mut output: ffi::DISPLAY_DEVICEW = unsafe { mem::zeroed() };
output.cb = mem::size_of::<ffi::DISPLAY_DEVICEW>() as ffi::DWORD;
// getting the DISPLAY_DEVICEW object of the current device
let output = {
let mut output: ffi::DISPLAY_DEVICEW = unsafe { mem::zeroed() };
output.cb = mem::size_of::<ffi::DISPLAY_DEVICEW>() as ffi::DWORD;
if unsafe { ffi::EnumDisplayDevicesW(ptr::null(), id as ffi::DWORD, &mut output, 0) } == 0 {
break
}
if unsafe { ffi::EnumDisplayDevicesW(ptr::null(),
id as ffi::DWORD, &mut output, 0) } == 0
{
// the device doesn't exist, which means we have finished enumerating
break;
}
if (output.StateFlags & ffi::DISPLAY_DEVICE_ACTIVE) == 0 ||
(output.StateFlags & ffi::DISPLAY_DEVICE_MIRRORING_DRIVER) != 0
{
continue
}
if (output.StateFlags & ffi::DISPLAY_DEVICE_ACTIVE) == 0 ||
(output.StateFlags & ffi::DISPLAY_DEVICE_MIRRORING_DRIVER) != 0
{
// the device is not active
// the Win32 api usually returns a lot of inactive devices
continue;
}
output
};
// computing the human-friendly name
let readable_name = String::from_utf16_lossy(output.DeviceString.as_slice());
let readable_name = readable_name.as_slice().trim_right_chars(0 as char).to_string();
// getting the position
let position = unsafe {
let mut dev: ffi::DEVMODE = mem::zeroed();
dev.dmSize = mem::size_of::<ffi::DEVMODE>() as ffi::WORD;
@ -36,13 +63,14 @@ pub fn get_available_monitors() -> Vec<MonitorID> {
if ffi::EnumDisplaySettingsExW(output.DeviceName.as_ptr(), ffi::ENUM_CURRENT_SETTINGS,
&mut dev, 0) == 0
{
continue
continue;
}
let point: &ffi::POINTL = mem::transmute(&dev.union1);
(point.x as uint, point.y as uint)
};
// adding to the resulting list
result.push(MonitorID {
name: output.DeviceName,
readable_name: readable_name,
@ -54,7 +82,11 @@ pub fn get_available_monitors() -> Vec<MonitorID> {
result
}
/// Win32 implementation of the main `get_primary_monitor` function.
pub fn get_primary_monitor() -> MonitorID {
// we simply get all available monitors and return the one with the `PRIMARY_DEVICE` flag
// TODO: it is possible to query the win32 API for the primary monitor, this should be done
// instead
for monitor in get_available_monitors().move_iter() {
if (monitor.flags & ffi::DISPLAY_DEVICE_PRIMARY_DEVICE) != 0 {
return monitor
@ -65,14 +97,19 @@ pub fn get_primary_monitor() -> MonitorID {
}
impl MonitorID {
/// See the docs if the crate root file.
pub fn get_name(&self) -> Option<String> {
Some(self.readable_name.clone())
}
/// This is a Win32-only function for `MonitorID` that returns the system name of the device.
pub fn get_system_name(&self) -> &[ffi::WCHAR] {
self.name.as_slice()
}
/// This is a Win32-only function for `MonitorID` that returns the position of the
/// monitor on the desktop.
/// A window that is positionned at these coordinates will overlap the monitor.
pub fn get_position(&self) -> (uint, uint) {
self.position
}