nephele
/
haiku-website
0
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
haiku-website/static/legacy-docs/bebook/BDirectWindow.html

145 lines
24 KiB
HTML
Raw Permalink Blame History

This file contains invisible Unicode characters

This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>The Be Book - Classes And Methods - The Game Kit</title><link rel="stylesheet" href="be_book.css" type="text/css" media="all" /><link rel="shortcut icon" type="image/vnd.microsoft.icon" href="./images/favicon.ico" /><!--[if IE]>
<link rel="stylesheet" type="text/css" href="be_book_ie.css" />
<![endif]--><meta name="generator" content="DocBook XSL Stylesheets V1.73.2" /><meta name="keywords" content="Access, BeOS, BeBook, API" /><link rel="start" href="index.html" title="The Be Book" /><link rel="up" href="TheGameKit.html" title="The Game Kit" /><link rel="prev" href="TheGameKit.html" title="The Game Kit" /><link rel="next" href="BFileGameSound.html" title="BFileGameSound" /></head><body><div id="header"><div id="headerT"><div id="headerTL"><a accesskey="p" href="TheGameKit.html" title="The Game Kit"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a accesskey="u" href="TheGameKit.html" title="The Game Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a accesskey="n" href="BFileGameSound.html" title="BFileGameSound"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="headerTR"><div id="navigpeople"><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div><div class="navigboxed" id="navigindex"><a accesskey="i" href="ClassIndex.html" title="Index">I</a></div><div class="navigboxed" id="naviglang" title="English">en</div></div><div id="headerTC">The Be Book - Classes And Methods - The Game Kit</div></div><div id="headerB">Prev: <a href="TheGameKit.html">The Game Kit</a>  Up: <a href="TheGameKit.html">The Game Kit</a>  Next: <a href="BFileGameSound.html">BFileGameSound</a></div><hr /></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h2 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BDirectWindow"></a>BDirectWindow</h2></div></div></div><a id="id946810" class="indexterm"></a><div class="classheader"><table border="0"><colgroup><col /><col /></colgroup><tbody><tr><td><table width="100%" border="0"><colgroup><col /><col /></colgroup><tbody><tr><td>Derived From:</td><td><a class="link" href="BWindow.html" title="BWindow">BWindow</a></td></tr><tr><td>Mix-in Classes:</td><td>–</td></tr><tr><td>Declared In:</td><td><code class="filename">kit/game/DirectWindow.h</code></td></tr><tr><td>Library:</td><td><code class="filename">libgame.so</code></td></tr><tr><td>Allocation:</td><td>–</td></tr></tbody></table></td><td>
<a class="link overview" href="BDirectWindow_Overview.html" title="BDirectWindow">Class Overview</a>
<div class="toc"><ul><li><span class="section"><a href="BDirectWindow.html#BDirectWindow_ConstructorDestructor">Constructor and Destructor</a></span></li><li><span class="section"><a href="BDirectWindow.html#BDirectWindow_HookFunctions">Hook Functions</a></span></li><li><span class="section"><a href="BDirectWindow.html#BDirectWindow_MemberFunctions">Member Functions</a></span></li></ul></div>
</td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BDirectWindow_ConstructorDestructor"></a>Constructor and Destructor</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BDirectWindow_Constructor"></a>BDirectWindow()</h4></div></div></div><div class="synopsisgroup">
<code class="constructorsynopsis cpp"><span class="methodname">BDirectWindow</span>(<span class="methodparam"><span class="type"><a class="link" href="BRect.html" title="BRect"><code class="classname">BRect</code></a> </span><span class="parameter">frame</span></span>,<br />              <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">title</span></span>,<br />              <span class="methodparam"><span class="type">window_type </span><span class="parameter">type</span></span>,<br />              <span class="methodparam"><span class="type">uint32 </span><span class="parameter">flags</span></span>,<br />              <span class="methodparam"><span class="type">uint32 </span><span class="parameter">workspace</span><span class="initializer"> = <span class="constant">B_CURRENT_WORKSPACE</span></span></span>);</code>
<code class="constructorsynopsis cpp"><span class="methodname">BDirectWindow</span>(<span class="methodparam"><span class="type"><a class="link" href="BRect.html" title="BRect"><code class="classname">BRect</code></a> </span><span class="parameter">frame</span></span>,<br />              <span class="methodparam"><span class="modifier">const </span><span class="type">char* </span><span class="parameter">title</span></span>,<br />              <span class="methodparam"><span class="type">window_look </span><span class="parameter">look</span></span>,<br />              <span class="methodparam"><span class="type">window_feel </span><span class="parameter">feel</span></span>,<br />              <span class="methodparam"><span class="type">uint32 </span><span class="parameter">flags</span></span>,<br />              <span class="methodparam"><span class="type">uint32 </span><span class="parameter">workspace</span><span class="initializer"> = <span class="constant">B_CURRENT_WORKSPACE</span></span></span>);</code>
</div><p>Creates and returns a new <code class="classname">BDirectWindow</code> object. This is functionally
equivalent to the <a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a>
<a class="link" href="BWindow.html#BWindow_Constructor" title="BWindow()">constructor</a>, except the resulting <code class="classname">BDirectWindow</code>
supports direct window operations.</p><p>You will probably want to set up a flag to keep track of whether or not
the direct window's connection to the screen is viable. In the
constructor, you should set this flag (let's call it <code class="varname">fConnectionDisabled</code>
) to <code class="constant">false</code>, which indicates to both
<a class="link" href="BDirectWindow.html#BDirectWindow_DirectConnected" title="DirectConnected()"><code class="methodname">DirectConnected()</code></a>
and your drawing
thread that the window is not in the process of being deconstructed. The
destructor would then set this flag to <code class="constant">true</code> before terminating the
connection to avoid the unlikely possibility of the connection trying to
restart while the <code class="classname">BDirectWindow</code> is being dismantled.</p><p>You'll also need other flags or semaphores (or benaphores) to manage the
interaction between the <code class="classname">BDirectWindow</code> and your drawing thread.</p><p>See the sample code in
"<a class="link" href="BDirectWindow_Overview.html#BDirectWindow_Overview_Using_Direct_Window" title="Using a Direct Window">Using a Direct Window</a>"
for an example.</p></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BDirectWindow_Destructor"></a>~BDirectWindow()</h4></div></div></div><code class="destructorsynopsis cpp"><span class="methodname">~BDirectWindow</span>();</code><p>Frees all memory the <code class="classname">BDirectWindow</code> object allocated for itself. You
should never delete a <code class="classname">BDirectWindow</code> object; call its
<a class="link" href="BWindow.html#BWindow_Quit" title="Quit()"><code class="methodname">Quit()</code></a>
function instead (inherited from <a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a>).</p><p>Your <code class="classname">BDirectWindow</code> destructor should begin by setting the
<code class="varname">fConnectionDisabled</code> flag to <code class="constant">true</code>, to prevent
<a class="link" href="BDirectWindow.html#BDirectWindow_DirectConnected" title="DirectConnected()"><code class="methodname">DirectConnected()</code></a> from
attempting to reconnect to the direct window while it's being
deconstructed.</p><p>Then you should call
<a class="link" href="BWindow.html#BWindow_Hide"><code class="methodname">Hide()</code></a> and
<a class="link" href="BWindow.html#BWindow_Sync"><code class="methodname">Sync()</code></a> to force the direct window to
disconnect direct access (both inherited from
<a class="link" href="BWindow.html" title="BWindow"><code class="classname">BWindow</code></a>):</p><pre class="programlisting example cpp"><code class="classname">MyDirectWindow</code>::~<code class="classname">BDirectWindow</code>
{
<code class="varname">fConnectionDisabled</code> = <code class="constant">true</code>;
<code class="methodname">Hide</code>();
<code class="methodname">Sync</code>();
<span class="comment">/* complete usual destruction here */</span>
}</pre></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BDirectWindow_HookFunctions"></a>Hook Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BDirectWindow_DirectConnected"></a>DirectConnected()</h4></div></div></div><code class="methodsynopsis"><span class="modifier">virtual </span><span class="void">void </span><span class="methodname">DirectConnected</span>(<span class="methodparam"><span class="type">direct_buffer_info* </span><span class="parameter">info</span></span>);</code><p>
This hook function is the core of <code class="classname">BDirectWindow</code>. Your application should
override this function to learn about the state of the graphics display
onto which you're drawing, as well as to be informed of any changes that
occur.
</p><p>
This function is also called to suspend and resume your direct access
privileges.
</p><p>
Your code in this function should be as short as possible, because what
your <code class="methodname">DirectConnected()</code> function does can affect the performance of the
entire system. <code class="methodname">DirectConnected()</code> should only handle the immediate task of
dealing with changes in the direct drawing context, and shouldn't
normally do any actual drawing—that's what your drawing thread is
for.
</p><p>
If you have drawing that absolutely has to be done before you can safely
return control to the application server (see the note below), you may do
so, but your code should do the absolute minimum drawing necessary and
leave everything else to the drawing thread.
</p><div class="admonition note"><div class="title">Note</div><div class="graphic"><img class="icon" alt="Note" width="32" src="./images/admonitions/Info_32.png" /><div class="text"><p><code class="methodname">DirectConnected()</code> should only return when it can guarantee to the
application server that the request specified by <code class="parameter">info</code> will be strictly
obeyed.</p></div></div></div><p>
The structure pointed to by <code class="parameter">info</code> goes away after <code class="methodname">DirectConnected()</code>
returns, so you should cache the information that interests you.
</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p>If your <code class="methodname">DirectConnected()</code> implementation doesn't handle a request
within three seconds, the <span class="application">Application Server</span> will intentionally crash
your application under the assumption that it's deadlocked. Be sure to
handle requests as quickly as possible.</p></div></div></div><p>
See "<a class="link" href="BDirectWindow_Overview.html#BDirectWindow_Overview_GettingConnected" title="Getting Connected (and Staying That Way)">Getting
Connected (and Staying That Way)</a>" for more
information about the <span class="type">direct_buffer_info</span> structure.
</p></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><hr /><div xmlns:d="http://docbook.org/ns/docbook"><h3 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BDirectWindow_MemberFunctions"></a>Member Functions</h3></div></div></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BDirectWindow_GetClippingRegion"></a>GetClippingRegion()</h4></div></div></div><code class="methodsynopsis cpp"><span class="type">status_t </span><span class="methodname">GetClippingRegion</span>(<span class="methodparam"><span class="type"><a class="link" href="BRegion.html" title="BRegion"><code class="classname">BRegion</code></a>* </span><span class="parameter">region</span></span>,<br />                           <span class="methodparam"><span class="type"><a class="link" href="BPoint.html" title="BPoint"><code class="classname">BPoint</code></a>* </span><span class="parameter">origin</span><span class="initializer"> = <span class="constant">NULL</span></span></span>) <span class="modifier">const</span>;</code><p>Sets the specified <code class="parameter">region</code> to match the current
clipping region of the direct window. If <code class="parameter">origin</code> is
specified, each point in the region is offset by the
<code class="parameter">origin</code>, resulting in a <a class="link" href="BRegion.html" title="BRegion"><code class="classname">BRegion</code></a> that's localized to
your application's vision of where in space the origin is (relative to the
origin of the screen's frame buffer).</p><p>Although the <span class="type">direct_buffer_info</span> structure contains the
clipping region of a direct window, it's not in standard <a class="link" href="BRegion.html" title="BRegion"><code class="classname">BRegion</code></a> form. This function
is provided so you can obtain a standard <a class="link" href="BRegion.html" title="BRegion"><code class="classname">BRegion</code></a> if you need
one.</p><div class="admonition warning"><div class="title">Warning</div><div class="graphic"><img class="icon" alt="Warning" width="32" src="./images/admonitions/Stop_32.png" /><div class="text"><p>The <code class="methodname">GetClippingRegion()</code> function can only be called from the
<a class="link" href="BDirectWindow.html#BDirectWindow_DirectConnected" title="DirectConnected()"><code class="methodname">DirectConnected()</code></a>
function; calling it from outside
<a class="link" href="BDirectWindow.html#BDirectWindow_DirectConnected" title="DirectConnected()"><code class="methodname">DirectConnected()</code></a>
will return invalid results.</p></div></div></div><p>If you need to cache the clipping region of your window and need a
<a class="link" href="BRegion.html" title="BRegion"><code class="classname">BRegion</code></a> for clipping
purposes, you could use the following code inside
your <a class="link" href="BDirectWindow.html#BDirectWindow_DirectConnected" title="DirectConnected()"><code class="methodname">DirectConnected()</code></a>
function:</p><pre class="programlisting example cpp"><a class="link" href="BRegion.html" title="BRegion"><code class="classname">BRegion</code></a> <code class="varname">rgn</code>;
<code class="methodname">GetClippingRegion</code>(&amp;<code class="varname">rgn</code>);</pre><p>
This serves a double purpose: it obtains the clipping region in
<a class="link" href="BRegion.html" title="BRegion"><code class="classname">BRegion</code></a>
form, and it returns a copy of the region that you can maintain locally.
However, it may be more efficient to copy the clipping region by hand,
since the clipping rectangle list used by <code class="classname">BDirectWindow</code> uses integer
numbers, while <a class="link" href="BRegion.html" title="BRegion"><code class="classname">BRegion</code></a> uses floating-point.
</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>The clipping region was successfully returned.</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ERROR</code>.</span></p></td><td><p>An error occurred while trying to
obtain the clipping region.</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BDirectWindow_IsFullScreen"></a><a id="BDirectWindow_SetFullScreen"></a>
IsFullScreen(), SetFullScreen()</h4></div></div></div><code class="methodsynopsis"><span class="type">bool </span><span class="methodname">IsFullScreen</span>() <span class="modifier">const</span>;</code><code class="methodsynopsis"><span class="type">status_t </span><span class="methodname">SetFullScreen</span>(<span class="methodparam"><span class="type">bool </span><span class="parameter">enable</span></span>);</code><p><code class="methodname">IsFullScreen()</code> returns
<code class="constant">true</code> if the direct window is in full-screen exclusive
mode, or <code class="constant">false</code> if it's in window mode.</p><p>The value returned by <code class="methodname">IsFullScreen()</code> is
indeterminate if a call to <code class="methodname">SetFullScreen()</code> is in
progress—if this is the case, you shouldn't rely on the resulting
value. Instead, it would be safer to maintain a state setting of your own
and use that value.</p><p><code class="methodname">SetFullScreen()</code> enables full-screen
exclusive mode if the <code class="parameter">enable</code> flag is
<code class="constant">true</code>. To switch to window mode, pass
<code class="constant">false</code>. The <a class="link" href="BDirectWindow.html#BDirectWindow_SupportsWindowMode" title="SupportsWindowMode()"><code class="methodname">SupportsWindowMode()
</code></a> function can be used to determine whether or not the
video card is capable of supporting window mode. See
"<a class="link" href="BDirectWindow_Overview.html#BDirectWindow_Overview_Window_Vs_Fullscreen" title="Window Mode vs. Full Screen Mode">Window Mode vs.
Full Screen Mode</a>" for a detailed explanation of the differences
between these modes.</p><p>When your window is in full screen mode, it will always have the
focus, and no other window can come in front of it.</p><p><code class="methodname">SetFullScreen()</code> can return any of the
following result codes.</p><table class="variablelist returncodes"><thead><tr><th>Return Code</th><th>Description</th></tr></thead><tbody><tr><td><p><span class="term"><code class="constant">B_OK</code>.</span></p></td><td><p>
The mode was successfully changed.
</p></td></tr><tr><td><p><span class="term"><code class="constant">B_ERROR</code>.</span></p></td><td><p>
An error occurred while trying to switch between full screen
and window modes<br />(for example, another window may already be in
full-screen exclusive mode in the same workspace).
</p></td></tr></tbody></table></div><div class="section"><div xmlns="" xmlns:d="http://docbook.org/ns/docbook" class="titlepage"><div><div xmlns:d="http://docbook.org/ns/docbook"><h4 xmlns="http://www.w3.org/1999/xhtml" class="title"><a id="BDirectWindow_SupportsWindowMode"></a>SupportsWindowMode()</h4></div></div></div><code class="methodsynopsis cpp"><span class="modifier">static </span><span class="type">bool </span><span class="methodname">SupportsWindowMode</span>(<span class="methodparam"><span class="type">screen_id </span><span class="parameter">id</span><span class="initializer"> = <span class="constant">B_MAIN_SCREEN_ID</span></span></span>);</code><p>Returns <code class="constant">true</code> if the specified screen supports window mode; if you require
the ability to directly access the frame buffer of a window (rather than
occupying the whole screen), you should call this function to be sure
that the graphics hardware in the computer running your application
supports it. Because this is a static function, you don't have to
construct a <code class="classname">BDirectWindow</code> object to call it:</p><pre class="programlisting example cpp">if (<code class="classname">BDirectWindow</code>::<code class="methodname">SupportsWindowMode</code>()) {
<span class="comment">/* do stuff here */</span>
}</pre><p>In particular, window mode requires a graphics card with <acronym class="acronym">DMA</acronym> support and
a hardware cursor; older video cards may not be capable of supporting
window mode.</p><p>If window mode isn't supported, but you still select window mode,
<a class="link" href="BDirectWindow.html#BDirectWindow_DirectConnected" title="DirectConnected()"><code class="methodname">DirectConnected()</code></a>
will never be called (so you'll never be authorized for
direct frame buffer access).</p><p>Even if window mode isn't supported, you can still use <code class="classname">BDirectWindow</code>
objects for full-screen direct access to the frame buffer, but it's
recommended that you avoid direct video <acronym class="acronym">DMA</acronym> or the use of parallel
drawing threads that use both direct frame buffer access and
<a class="link" href="BView.html" title="BView"><code class="classname">BView</code></a> calls
(because it's likely that such a graphics card won't handle the parallel
access and freeze the <acronym class="acronym">PCI</acronym> bus—and that would be bad).</p></div></div></div><div id="footer"><hr /><div id="footerT">Prev: <a href="TheGameKit.html">The Game Kit</a>  Up: <a href="TheGameKit.html">The Game Kit</a>  Next: <a href="BFileGameSound.html">BFileGameSound</a> </div><div id="footerB"><div id="footerBL"><a href="TheGameKit.html" title="The Game Kit"><img src="./images/navigation/prev.png" alt="Prev" /></a> <a href="TheGameKit.html" title="The Game Kit"><img src="./images/navigation/up.png" alt="Up" /></a> <a href="BFileGameSound.html" title="BFileGameSound"><img src="./images/navigation/next.png" alt="Next" /></a></div><div id="footerBR"><div><a href="http://www.haiku-os.org"><img src="./images/People_24.png" alt="haiku-os.org" title="Visit The Haiku Website" /></a></div><div class="navighome" title="Home"><a accesskey="h" href="index.html"><img src="./images/navigation/home.png" alt="Home" /></a></div></div><div id="footerBC"><a href="http://www.access-company.com/home.html" title="ACCESS Co."><img alt="Access Company" src="./images/access_logo.png" /></a></div></div></div><div id="licenseFooter"><div id="licenseFooterBL"><a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/" title="Creative Commons License"><img alt="Creative Commons License" style="border-width:0" src="https://licensebuttons.net/l/by-nc-nd/3.0/88x31.png" /></a></div><div id="licenseFooterBR"><a href="./LegalNotice.html">Legal Notice</a></div><div id="licenseFooterBC"><span id="licenseText">This work is licensed under a
<a rel="license" href="http://creativecommons.org/licenses/by-nc-nd/3.0/">Creative
Commons Attribution-Non commercial-No Derivative Works 3.0 License</a>.</span></div></div></body></html>
Reference in New Issue View Git Blame Copy Permalink