man/waffle_window.3.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   Copyright Intel 2012
   7
   8   This manual page is licensed under the Creative Commons Attribution-ShareAlike 3.0 United States License (CC BY-SA 3.0
   9   US). To view a copy of this license, visit http://creativecommons.org.license/by-sa/3.0/us.
  10 -->
  11
  12 <refentry
  13     id="waffle_window"
  14     xmlns:xi="http://www.w3.org/2001/XInclude">
  15
  16   <!-- See http://www.docbook.org/tdg/en/html/refentry.html. -->
  17
  18   <refmeta>
  19     <refentrytitle>waffle_window</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>waffle_window</refname>
  25     <refname>waffle_window_create</refname>
  26     <refname>waffle_window_destroy</refname>
  27     <refname>waffle_window_show</refname>
  28     <refname>waffle_window_swap_buffers</refname>
  29     <refname>waffle_window_get_native</refname>
  30     <refpurpose>class <classname>waffle_window</classname></refpurpose>
  31   </refnamediv>
  32
  33   <refentryinfo>
  34     <title>Waffle Manual</title>
  35     <productname>waffle</productname>
  36     <xi:include href="common/author-chad.versace.xml"/>
  37     <xi:include href="common/copyright.xml"/>
  38     <xi:include href="common/legalnotice.xml"/>
  39   </refentryinfo>
  40
  41   <refsynopsisdiv>
  42
  43     <funcsynopsis language="C">
  44
  45       <funcsynopsisinfo>
  46 #include &lt;waffle.h&gt;
  47
  48 struct waffle_window;
  49       </funcsynopsisinfo>
  50
  51       <funcprototype>
  52         <funcdef>struct waffle_window* <function>waffle_window_create</function></funcdef>
  53         <paramdef>struct waffle_window *<parameter>config</parameter></paramdef>
  54         <paramdef>int32_t <parameter>width</parameter></paramdef>
  55         <paramdef>int32_t <parameter>height</parameter></paramdef>
  56       </funcprototype>
  57
  58       <funcprototype>
  59         <funcdef>struct waffle_window* <function>waffle_window_create2</function></funcdef>
  60         <paramdef>struct waffle_window *<parameter>config</parameter></paramdef>
  61         <paramdef>const intptr_t <parameter>attrib_list</parameter>[]</paramdef>
  62       </funcprototype>
  63
  64       <funcprototype>
  65         <funcdef>bool <function>waffle_window_destroy</function></funcdef>
  66         <paramdef>struct waffle_window *<parameter>self</parameter></paramdef>
  67       </funcprototype>
  68
  69       <funcprototype>
  70         <funcdef>bool <function>waffle_window_show</function></funcdef>
  71         <paramdef>struct waffle_window *<parameter>self</parameter></paramdef>
  72       </funcprototype>
  73
  74       <funcprototype>
  75         <funcdef>bool <function>waffle_window_swap_buffers</function></funcdef>
  76         <paramdef>struct waffle_window *<parameter>self</parameter></paramdef>
  77       </funcprototype>
  78
  79       <funcprototype>
  80         <funcdef>union waffle_native_window* <function>waffle_window_get_native</function></funcdef>
  81         <paramdef>struct waffle_window *<parameter>self</parameter></paramdef>
  82       </funcprototype>
  83
  84     </funcsynopsis>
  85   </refsynopsisdiv>
  86
  87   <refsect1>
  88     <title>Description</title>
  89
  90     <variablelist>
  91
  92       <varlistentry>
  93         <term><type>struct waffle_window</type></term><listitem><para>
  94             An opaque type.
  95           </para>
  96         </listitem>
  97       </varlistentry>
  98
  99       <varlistentry>
 100         <term><function>waffle_window_create()</function></term>
 101         <listitem>
 102           <para>
 103             Create a window with the properties specified by <parameter>config</parameter>.
 104           </para>
 105           <para>
 106             If the platform allows, the window is not displayed onto the screen after creation. To display the window,
 107             call <function>waffle_window_show()</function>.
 108           </para>
 109         </listitem>
 110       </varlistentry>
 111
 112       <varlistentry>
 113         <term><function>waffle_window_create2()</function></term>
 114         <listitem>
 115           <para>
 116             Feature test macro: <code>WAFFLE_API_VERSION >= 0x0106</code>.
 117             (See <citerefentry><refentrytitle>waffle_feature_test_macros</refentrytitle><manvolnum>7</manvolnum></citerefentry>).
 118           </para>
 119           <para>
 120             Create a window with the properties specified by
 121             <parameter>config</parameter> and
 122             <parameter>attrib_list</parameter>.
 123
 124             <parameter>attrib_list</parameter> must specify the window size
 125             either with the attributes
 126             <constant>WAFFLE_WINDOW_WIDTH</constant> and
 127             <constant>WAFFLE_WINDOW_HEIGHT</constant> having positive values
 128             &lt;= <constant>INT32_MAX</constant>,
 129             or with the attribute
 130             <constant>WAFFLE_WINDOW_FULLSCREEN</constant> equal to true(1).
 131           </para>
 132         </listitem>
 133       </varlistentry>
 134
 135       <varlistentry>
 136         <term><function>waffle_window_destroy()</function></term>
 137         <listitem>
 138           <para>
 139             Destroy the window and release its memory.
 140           </para>
 141         </listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term><function>waffle_window_show()</function></term>
 146         <listitem>
 147           <para>
 148             Show the window on the display.  If the window is already shown, or if the native platform does not support
 149             showing windows (such as GBM), then do nothing and returns true.
 150           </para>
 151         </listitem>
 152       </varlistentry>
 153
 154       <varlistentry>
 155         <term><function>waffle_window_swap_buffers()</function></term>
 156         <listitem>
 157           <para>
 158             If the window is double-buffered, then implicitly call <function>glFlush()</function> and post the contents
 159             of the back buffer to the front buffer. If the window is front-buffered, then do nothing. For
 160             platform-specific details of swap semantics, see the specification for the relevant native platform:
 161             the <ulink url="http://www.opengl.org/registry/doc/glx1.4.pdf">GLX 1.4 Specification</ulink>,
 162             the <ulink url="http://www.khronos.org/registry/egl/specs/eglspec.1.4.20110406.pdf">EGL 1.4 Specification</ulink>,
 163             or the <ulink url="https://developer.apple.com/library/mac/#documentation/graphicsimaging/reference/CGL_OpenGL/Reference/reference.html">CGL Reference</ulink>.
 164           </para>
 165         </listitem>
 166       </varlistentry>
 167
 168       <varlistentry>
 169         <term><function>waffle_window_get_native()</function></term>
 170         <listitem>
 171           <para>
 172             Get the window's underlying native objects. Use
 173             <citerefentry><refentrytitle><function>free</function></refentrytitle><manvolnum>3</manvolnum></citerefentry> to deallocate the
 174             returned pointer.
 175             See <citerefentry><refentrytitle><function>waffle_native</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 176             for the definition of <type>union waffle_native_window</type>.
 177           </para>
 178         </listitem>
 179       </varlistentry>
 180
 181     </variablelist>
 182   </refsect1>
 183
 184   <refsect1>
 185     <title>Return Value</title>
 186     <xi:include href="common/return-value.xml"/>
 187   </refsect1>
 188
 189   <refsect1>
 190     <title>Errors</title>
 191
 192     <xi:include href="common/error-codes.xml"/>
 193
 194     <para>
 195       No errors are specific to the <type>waffle_window</type> functions.
 196     </para>
 197   </refsect1>
 198
 199   <xi:include href="common/issues.xml"/>
 200
 201   <refsect1>
 202     <title>See Also</title>
 203     <para>
 204       <citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 205     </para>
 206   </refsect1>
 207
 208 </refentry>
 209
 210 <!--
 211 vim:tw=120 et ts=2 sw=2:
 212 -->