You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
155 lines
16 KiB
155 lines
16 KiB
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
|
|
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
|
|
<meta name="generator" content="Doxygen 1.8.11"/>
|
|
<title>GLFW: Monitor guide</title>
|
|
<link href="tabs.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="jquery.js"></script>
|
|
<script type="text/javascript" src="dynsections.js"></script>
|
|
<link href="search/search.css" rel="stylesheet" type="text/css"/>
|
|
<script type="text/javascript" src="search/searchdata.js"></script>
|
|
<script type="text/javascript" src="search/search.js"></script>
|
|
<script type="text/javascript">
|
|
$(document).ready(function() { init_search(); });
|
|
</script>
|
|
<link href="doxygen.css" rel="stylesheet" type="text/css" />
|
|
<link href="extra.css" rel="stylesheet" type="text/css"/>
|
|
</head>
|
|
<body>
|
|
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
|
|
<div id="titlearea">
|
|
<div class="glfwheader">
|
|
<a href="http://www.glfw.org/" id="glfwhome">GLFW</a>
|
|
<ul class="glfwnavbar">
|
|
<li><a href="http://www.glfw.org/documentation.html">Documentation</a></li>
|
|
<li><a href="http://www.glfw.org/download.html">Download</a></li>
|
|
<li><a href="http://www.glfw.org/media.html">Media</a></li>
|
|
<li><a href="http://www.glfw.org/community.html">Community</a></li>
|
|
</ul>
|
|
</div>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.8.11 -->
|
|
<script type="text/javascript">
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search');
|
|
</script>
|
|
<div id="navrow1" class="tabs">
|
|
<ul class="tablist">
|
|
<li><a href="index.html"><span>Main Page</span></a></li>
|
|
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
|
|
<li><a href="modules.html"><span>Modules</span></a></li>
|
|
<li><a href="annotated.html"><span>Data Structures</span></a></li>
|
|
<li><a href="files.html"><span>Files</span></a></li>
|
|
<li>
|
|
<div id="MSearchBox" class="MSearchBoxInactive">
|
|
<span class="left">
|
|
<img id="MSearchSelect" src="search/mag_sel.png"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
alt=""/>
|
|
<input type="text" id="MSearchField" value="Search" accesskey="S"
|
|
onfocus="searchBox.OnSearchFieldFocus(true)"
|
|
onblur="searchBox.OnSearchFieldFocus(false)"
|
|
onkeyup="searchBox.OnSearchFieldChange(event)"/>
|
|
</span><span class="right">
|
|
<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.png" alt=""/></a>
|
|
</span>
|
|
</div>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<!-- window showing the filter options -->
|
|
<div id="MSearchSelectWindow"
|
|
onmouseover="return searchBox.OnSearchSelectShow()"
|
|
onmouseout="return searchBox.OnSearchSelectHide()"
|
|
onkeydown="return searchBox.OnSearchSelectKey(event)">
|
|
</div>
|
|
|
|
<!-- iframe showing the search results (closed by default) -->
|
|
<div id="MSearchResultsWindow">
|
|
<iframe src="javascript:void(0)" frameborder="0"
|
|
name="MSearchResults" id="MSearchResults">
|
|
</iframe>
|
|
</div>
|
|
|
|
</div><!-- top -->
|
|
<div class="header">
|
|
<div class="headertitle">
|
|
<div class="title">Monitor guide </div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="toc"><h3>Table of Contents</h3>
|
|
<ul><li class="level1"><a href="#monitor_object">Monitor objects</a><ul><li class="level2"><a href="#monitor_monitors">Retrieving monitors</a></li>
|
|
<li class="level2"><a href="#monitor_event">Monitor configuration changes</a></li>
|
|
</ul>
|
|
</li>
|
|
<li class="level1"><a href="#monitor_properties">Monitor properties</a><ul><li class="level2"><a href="#monitor_modes">Video modes</a></li>
|
|
<li class="level2"><a href="#monitor_size">Physical size</a></li>
|
|
<li class="level2"><a href="#monitor_pos">Virtual position</a></li>
|
|
<li class="level2"><a href="#monitor_name">Human-readable name</a></li>
|
|
<li class="level2"><a href="#monitor_gamma">Gamma ramp</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<div class="textblock"><p>This guide introduces the monitor related functions of GLFW. For details on a specific function in this category, see the <a class="el" href="group__monitor.html">Monitor reference</a>. There are also guides for the other areas of GLFW.</p>
|
|
<ul>
|
|
<li><a class="el" href="intro_guide.html">Introduction to the API</a></li>
|
|
<li><a class="el" href="window_guide.html">Window guide</a></li>
|
|
<li><a class="el" href="context_guide.html">Context guide</a></li>
|
|
<li><a class="el" href="vulkan_guide.html">Vulkan guide</a></li>
|
|
<li><a class="el" href="input_guide.html">Input guide</a></li>
|
|
</ul>
|
|
<h1><a class="anchor" id="monitor_object"></a>
|
|
Monitor objects</h1>
|
|
<p>A monitor object represents a currently connected monitor and is represented as a pointer to the <a href="https://en.wikipedia.org/wiki/Opaque_data_type">opaque</a> type <a class="el" href="group__monitor.html#ga8d9efd1cde9426692c73fe40437d0ae3">GLFWmonitor</a>. Monitor objects cannot be created or destroyed by the application and retain their addresses until the monitors they represent are disconnected or until the library is <a class="el" href="intro_guide.html#intro_init_terminate">terminated</a>.</p>
|
|
<p>Each monitor has a current video mode, a list of supported video modes, a virtual position, a human-readable name, an estimated physical size and a gamma ramp. One of the monitors is the primary monitor.</p>
|
|
<p>The virtual position of a monitor is in <a class="el" href="intro_guide.html#coordinate_systems">screen coordinates</a> and, together with the current video mode, describes the viewports that the connected monitors provide into the virtual desktop that spans them.</p>
|
|
<p>To see how GLFW views your monitor setup and its available video modes, run the <code>monitors</code> test program.</p>
|
|
<h2><a class="anchor" id="monitor_monitors"></a>
|
|
Retrieving monitors</h2>
|
|
<p>The primary monitor is returned by <a class="el" href="group__monitor.html#ga721867d84c6d18d6790d64d2847ca0b1">glfwGetPrimaryMonitor</a>. It is the user's preferred monitor and is usually the one with global UI elements like task bar or menu bar.</p>
|
|
<div class="fragment"><div class="line"><a class="code" href="group__monitor.html#ga8d9efd1cde9426692c73fe40437d0ae3">GLFWmonitor</a>* primary = <a class="code" href="group__monitor.html#ga721867d84c6d18d6790d64d2847ca0b1">glfwGetPrimaryMonitor</a>();</div></div><!-- fragment --><p>You can retrieve all currently connected monitors with <a class="el" href="group__monitor.html#ga3fba51c8bd36491d4712aa5bd074a537">glfwGetMonitors</a>. See the reference documentation for the lifetime of the returned array.</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">int</span> count;</div><div class="line"><a class="code" href="group__monitor.html#ga8d9efd1cde9426692c73fe40437d0ae3">GLFWmonitor</a>** monitors = <a class="code" href="group__monitor.html#ga3fba51c8bd36491d4712aa5bd074a537">glfwGetMonitors</a>(&count);</div></div><!-- fragment --><p>The primary monitor is always the first monitor in the returned array, but other monitors may be moved to a different index when a monitor is connected or disconnected.</p>
|
|
<h2><a class="anchor" id="monitor_event"></a>
|
|
Monitor configuration changes</h2>
|
|
<p>If you wish to be notified when a monitor is connected or disconnected, set a monitor callback.</p>
|
|
<div class="fragment"><div class="line"><a class="code" href="group__monitor.html#gac3fe0f647f68b731f99756cd81897378">glfwSetMonitorCallback</a>(monitor_callback);</div></div><!-- fragment --><p>The callback function receives the handle for the monitor that has been connected or disconnected and the event that occurred.</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">void</span> monitor_callback(<a class="code" href="group__monitor.html#ga8d9efd1cde9426692c73fe40437d0ae3">GLFWmonitor</a>* monitor, <span class="keywordtype">int</span> event)</div><div class="line">{</div><div class="line"> <span class="keywordflow">if</span> (event == <a class="code" href="glfw3_8h.html#abe11513fd1ffbee5bb9b173f06028b9e">GLFW_CONNECTED</a>)</div><div class="line"> {</div><div class="line"> <span class="comment">// The monitor was connected</span></div><div class="line"> }</div><div class="line"> <span class="keywordflow">else</span> <span class="keywordflow">if</span> (event == <a class="code" href="glfw3_8h.html#aab64b25921ef21d89252d6f0a71bfc32">GLFW_DISCONNECTED</a>)</div><div class="line"> {</div><div class="line"> <span class="comment">// The monitor was disconnected</span></div><div class="line"> }</div><div class="line">}</div></div><!-- fragment --><p>If a monitor is disconnected, any windows that are full screen on it get forced into windowed mode.</p>
|
|
<h1><a class="anchor" id="monitor_properties"></a>
|
|
Monitor properties</h1>
|
|
<p>Each monitor has a current video mode, a list of supported video modes, a virtual position, a human-readable name, an estimated physical size and a gamma ramp.</p>
|
|
<h2><a class="anchor" id="monitor_modes"></a>
|
|
Video modes</h2>
|
|
<p>GLFW generally does a good job selecting a suitable video mode when you create a full screen window, change its video mode or or make a windowed one full screen, but it is sometimes useful to know exactly which video modes are supported.</p>
|
|
<p>Video modes are represented as <a class="el" href="structGLFWvidmode.html">GLFWvidmode</a> structures. You can get an array of the video modes supported by a monitor with <a class="el" href="group__monitor.html#ga820b0ce9a5237d645ea7cbb4bd383458">glfwGetVideoModes</a>. See the reference documentation for the lifetime of the returned array.</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">int</span> count;</div><div class="line"><a class="code" href="structGLFWvidmode.html">GLFWvidmode</a>* modes = <a class="code" href="group__monitor.html#ga820b0ce9a5237d645ea7cbb4bd383458">glfwGetVideoModes</a>(monitor, &count);</div></div><!-- fragment --><p>To get the current video mode of a monitor call <a class="el" href="group__monitor.html#gafc1bb972a921ad5b3bd5d63a95fc2d52">glfwGetVideoMode</a>. See the reference documentation for the lifetime of the returned pointer.</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">const</span> <a class="code" href="structGLFWvidmode.html">GLFWvidmode</a>* mode = <a class="code" href="group__monitor.html#gafc1bb972a921ad5b3bd5d63a95fc2d52">glfwGetVideoMode</a>(monitor);</div></div><!-- fragment --><p>The resolution of a video mode is specified in <a class="el" href="intro_guide.html#coordinate_systems">screen coordinates</a>, not pixels.</p>
|
|
<h2><a class="anchor" id="monitor_size"></a>
|
|
Physical size</h2>
|
|
<p>The physical size of a monitor in millimetres, or an estimation of it, can be retrieved with <a class="el" href="group__monitor.html#ga7d8bffc6c55539286a6bd20d32a8d7ea">glfwGetMonitorPhysicalSize</a>. This has no relation to its current <em>resolution</em>, i.e. the width and height of its current <a class="el" href="monitor_guide.html#monitor_modes">video mode</a>.</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">int</span> widthMM, heightMM;</div><div class="line"><a class="code" href="group__monitor.html#ga7d8bffc6c55539286a6bd20d32a8d7ea">glfwGetMonitorPhysicalSize</a>(monitor, &widthMM, &heightMM);</div></div><!-- fragment --><p>This can, for example, be used together with the current video mode to calculate the DPI of a monitor.</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">double</span> dpi = mode-><a class="code" href="structGLFWvidmode.html#a698dcb200562051a7249cb6ae154c71d">width</a> / (widthMM / 25.4);</div></div><!-- fragment --><h2><a class="anchor" id="monitor_pos"></a>
|
|
Virtual position</h2>
|
|
<p>The position of the monitor on the virtual desktop, in <a class="el" href="intro_guide.html#coordinate_systems">screen coordinates</a>, can be retrieved with <a class="el" href="group__monitor.html#ga102f54e7acc9149edbcf0997152df8c9">glfwGetMonitorPos</a>.</p>
|
|
<div class="fragment"><div class="line"><span class="keywordtype">int</span> xpos, ypos;</div><div class="line"><a class="code" href="group__monitor.html#ga102f54e7acc9149edbcf0997152df8c9">glfwGetMonitorPos</a>(monitor, &xpos, &ypos);</div></div><!-- fragment --><h2><a class="anchor" id="monitor_name"></a>
|
|
Human-readable name</h2>
|
|
<p>The human-readable, UTF-8 encoded name of a monitor is returned by <a class="el" href="group__monitor.html#ga79a34ee22ff080ca954a9663e4679daf">glfwGetMonitorName</a>. See the reference documentation for the lifetime of the returned string.</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">const</span> <span class="keywordtype">char</span>* name = <a class="code" href="group__monitor.html#ga79a34ee22ff080ca954a9663e4679daf">glfwGetMonitorName</a>(monitor);</div></div><!-- fragment --><p>Monitor names are not guaranteed to be unique. Two monitors of the same model and make may have the same name. Only the monitor handle is guaranteed to be unique, and only until that monitor is disconnected.</p>
|
|
<h2><a class="anchor" id="monitor_gamma"></a>
|
|
Gamma ramp</h2>
|
|
<p>The gamma ramp of a monitor can be set with <a class="el" href="group__monitor.html#ga583f0ffd0d29613d8cd172b996bbf0dd">glfwSetGammaRamp</a>, which accepts a monitor handle and a pointer to a <a class="el" href="structGLFWgammaramp.html">GLFWgammaramp</a> structure.</p>
|
|
<div class="fragment"><div class="line"><a class="code" href="structGLFWgammaramp.html">GLFWgammaramp</a> ramp;</div><div class="line"><span class="keywordtype">unsigned</span> <span class="keywordtype">short</span> red[256], green[256], blue[256];</div><div class="line"></div><div class="line">ramp.<a class="code" href="structGLFWgammaramp.html#ad620e1cffbff9a32c51bca46301b59a5">size</a> = 256;</div><div class="line">ramp.<a class="code" href="structGLFWgammaramp.html#a2cce5d968734b685623eef913e635138">red</a> = red;</div><div class="line">ramp.<a class="code" href="structGLFWgammaramp.html#affccc6f5df47820b6562d709da3a5a3a">green</a> = green;</div><div class="line">ramp.<a class="code" href="structGLFWgammaramp.html#acf0c836d0efe29c392fe8d1a1042744b">blue</a> = blue;</div><div class="line"></div><div class="line"><span class="keywordflow">for</span> (i = 0; i < ramp.<a class="code" href="structGLFWgammaramp.html#ad620e1cffbff9a32c51bca46301b59a5">size</a>; i++)</div><div class="line">{</div><div class="line"> <span class="comment">// Fill out gamma ramp arrays as desired</span></div><div class="line">}</div><div class="line"></div><div class="line"><a class="code" href="group__monitor.html#ga583f0ffd0d29613d8cd172b996bbf0dd">glfwSetGammaRamp</a>(monitor, &ramp);</div></div><!-- fragment --><p>The gamma ramp data is copied before the function returns, so there is no need to keep it around once the ramp has been set.</p>
|
|
<dl class="section note"><dt>Note</dt><dd>It is recommended to use gamma ramps of size 256, as that is the size supported by all graphics cards on all platforms.</dd></dl>
|
|
<p>The current gamma ramp for a monitor is returned by <a class="el" href="group__monitor.html#gab7c41deb2219bde3e1eb756ddaa9ec80">glfwGetGammaRamp</a>. See the reference documentation for the lifetime of the returned structure.</p>
|
|
<div class="fragment"><div class="line"><span class="keyword">const</span> <a class="code" href="structGLFWgammaramp.html">GLFWgammaramp</a>* ramp = <a class="code" href="group__monitor.html#gab7c41deb2219bde3e1eb756ddaa9ec80">glfwGetGammaRamp</a>(monitor);</div></div><!-- fragment --><p>If you wish to set a regular gamma ramp, you can have GLFW calculate it for you from the desired exponent with <a class="el" href="group__monitor.html#ga6ac582625c990220785ddd34efa3169a">glfwSetGamma</a>, which in turn calls <a class="el" href="group__monitor.html#ga583f0ffd0d29613d8cd172b996bbf0dd">glfwSetGammaRamp</a> with the resulting ramp.</p>
|
|
<div class="fragment"><div class="line"><a class="code" href="group__monitor.html#ga6ac582625c990220785ddd34efa3169a">glfwSetGamma</a>(monitor, 1.0);</div></div><!-- fragment --> </div></div><!-- contents -->
|
|
<address class="footer">
|
|
<p>
|
|
Last update on Thu Aug 18 2016 for GLFW 3.2.1
|
|
</p>
|
|
</address>
|
|
</body>
|
|
</html>
|