man/waffle_init.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_init"
  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_init</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>waffle_init</refname>
  25     <refpurpose>Initialize waffle's per-process global state</refpurpose>
  26   </refnamediv>
  27
  28   <refentryinfo>
  29     <title>Waffle Manual</title>
  30     <productname>waffle</productname>
  31     <xi:include href="common/author-chad.versace.xml"/>
  32     <xi:include href="common/copyright.xml"/>
  33     <xi:include href="common/legalnotice.xml"/>
  34   </refentryinfo>
  35
  36   <refsynopsisdiv>
  37     <funcsynopsis>
  38       <funcsynopsisinfo><![CDATA[#include <waffle.h>]]></funcsynopsisinfo>
  39       <funcprototype>
  40         <funcdef>bool <function>waffle_init</function></funcdef>
  41         <paramdef>const int32_t <parameter>attrib_list</parameter>[]</paramdef>
  42       </funcprototype>
  43     </funcsynopsis>
  44   </refsynopsisdiv>
  45
  46   <refsect1>
  47     <title>Description</title>
  48
  49     <para>
  50       <function>waffle_init()</function> initializes the per-process global state of the waffle library with the
  51       attributes specified in <parameter>attrib_list</parameter>.  The set of attributes is documented below.
  52       <parameter>attrib_list</parameter> consists of a zero-terminated sequence of name/value pairs.
  53     </para>
  54
  55     <para>
  56       Most waffle functions emit an error if called when waffle is unitialized.  The small set of functions that can be
  57       successfully called before initialization are explicitly documented as such.
  58     </para>
  59
  60     <para>
  61       If a call to <function>waffle_init()</function> fails, no global state is initialized and the caller may safely
  62       attempt to call <function>waffle_init()</function> again.  If waffle has already been initialized by a successful
  63       call to <function>waffle_init()</function> one has to call <function>waffle_teardown()</function> to clear the
  64       global state. Otherwise calling <function>waffle_init()</function> again emits the error
  65       <errorcode>WAFFLE_ERROR_ALREADY_INITIALIZED</errorcode>.
  66     </para>
  67
  68   </refsect1>
  69
  70   <refsect1>
  71     <title>Attributes</title>
  72
  73     <variablelist>
  74
  75       <varlistentry>
  76         <term><constant>WAFFLE_PLATFORM</constant></term>
  77         <listitem>
  78           <para>
  79             This attribute is required. Possible values are:
  80
  81             <variablelist>
  82
  83               <varlistentry>
  84                 <term><constant>WAFFLE_PLATFORM_ANDROID</constant></term>
  85                 <listitem>
  86                   <para>
  87                     [Android] Use EGL on Android.
  88                   </para>
  89                 </listitem>
  90               </varlistentry>
  91
  92               <varlistentry>
  93                 <term><constant>WAFFLE_PLATFORM_GBM</constant></term>
  94                 <listitem>
  95                   <para>
  96                     [Linux] Use EGL with GBM, the "Generic Buffer Manager" provided by libgbm. This platform is
  97                     capable of OpenGL rendering without a display manager.
  98                   </para>
  99                 </listitem>
 100               </varlistentry>
 101
 102               <varlistentry>
 103                 <term><constant>WAFFLE_PLATFORM_CGL</constant></term>
 104                 <listitem>
 105                   <para>
 106                     [MacOS] Use CGL to create the
 107                     <citerefentry><refentrytitle><function>waffle_config</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 108                     and
 109                     <citerefentry><refentrytitle><function>waffle_context</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 110                     Use Cocoa to create the
 111                     <citerefentry><refentrytitle><function>waffle_window</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 112                   </para>
 113                 </listitem>
 114               </varlistentry>
 115
 116               <varlistentry>
 117                 <term><constant>WAFFLE_PLATFORM_GLX</constant></term>
 118                 <listitem>
 119                   <para>
 120                     [Linux only, MacOS not yet supported]
 121                   </para>
 122                 </listitem>
 123               </varlistentry>
 124               <varlistentry>
 125                 <term><constant>WAFFLE_PLATFORM_NACL</constant></term>
 126                 <listitem>
 127                   <para>
 128                     [Linux only, other systems not yet supported]
 129                   </para>
 130                 </listitem>
 131               </varlistentry>
 132               <varlistentry>
 133                 <term><constant>WAFFLE_PLATFORM_WAYLAND</constant></term>
 134                 <listitem>
 135                   <para>
 136                     [Linux] Use EGL with the Wayland display server.
 137                   </para>
 138                 </listitem>
 139               </varlistentry>
 140               <varlistentry>
 141                 <term><constant>WAFFLE_PLATFORM_WGL</constant></term>
 142                 <listitem>
 143                   <para>
 144                     [Windows] Use WGL on Windows.
 145                   </para>
 146                 </listitem>
 147               </varlistentry>
 148               <varlistentry>
 149                 <term><constant>WAFFLE_PLATFORM_X11_EGL</constant></term>
 150                 <listitem>
 151                   <para>
 152                     [Linux] Use EGL with the X11 display server.
 153                   </para>
 154                 </listitem>
 155               </varlistentry>
 156
 157             </variablelist>
 158           </para>
 159         </listitem>
 160       </varlistentry>
 161
 162     </variablelist>
 163   </refsect1>
 164
 165   <refsect1>
 166     <title>Return Value</title>
 167     <xi:include href="common/return-value.xml"/>
 168   </refsect1>
 169
 170   <refsect1>
 171     <title>Errors</title>
 172
 173     <xi:include href="common/error-codes.xml"/>
 174
 175     <para>
 176       Listed are the errors specific to <function>waffle_init()</function>.
 177     </para>
 178
 179     <variablelist>
 180
 181       <varlistentry>
 182         <term><errorcode>WAFFLE_ERROR_ALREADY_INITIALIZED</errorcode></term>
 183         <listitem>
 184           <para>
 185             Waffle has already been initialized with a successfull call to <function>waffle_init()</function>.
 186           </para>
 187         </listitem>
 188       </varlistentry>
 189
 190       <varlistentry>
 191         <term><errorcode>WAFFLE_ERROR_BAD_ATTRIBUTE</errorcode></term>
 192         <listitem>
 193           <para>
 194             An item in <parameter>attrib_list</parameter> is unrecognized or has an invalid value, or a required
 195             attribute is missing.
 196           </para>
 197         </listitem>
 198       </varlistentry>
 199
 200       <varlistentry>
 201         <term><errorcode>WAFFLE_ERROR_BUILT_WITHOUT_SUPPORT</errorcode></term>
 202         <listitem>
 203           <para>
 204             Waffle was built without support for the requested attribute.
 205           </para>
 206         </listitem>
 207       </varlistentry>
 208
 209     </variablelist>
 210
 211   </refsect1>
 212
 213   <refsect1>
 214     <title>Example</title>
 215
 216     <para>
 217       Initialize waffle for X11/EGL.
 218     </para>
 219
 220     <programlisting>
 221 <![CDATA[
 222 #include <waffle.h>
 223
 224 static const int32_t init_attrib_list[] = {
 225     WAFFLE_PLATFORM, WAFFLE_PLATFORM_X11_EGL,
 226     0,
 227 };
 228
 229 int
 230 main()
 231 {
 232     bool ok = waffle_init(init_attrib_list);
 233     if (ok)
 234         return EXIT_SUCCESS;
 235     else
 236         return EXIT_FAILURE;
 237 }
 238 ]]>
 239     </programlisting>
 240   </refsect1>
 241
 242   <xi:include href="common/issues.xml"/>
 243
 244   <refsect1>
 245     <title>See Also</title>
 246     <para>
 247       <citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 248     </para>
 249   </refsect1>
 250
 251 </refentry>
 252
 253 <!--
 254 vim:tw=120 et ts=2 sw=2:
 255 -->