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-lina.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_SURFACELESS_EGL</constant></term>
 126                 <listitem>
 127                   <para>
 128                     [Linux] Use EGL's "surfaceless" platform,
 129                     <ulink url="https://www.khronos.org/registry/egl/extensions/MESA/EGL_MESA_platform_surfaceless.txt">EGL_MESA_platform_surfaceless</ulink>.
 130                   </para>
 131                 </listitem>
 132               </varlistentry>
 133               <varlistentry>
 134                 <term><constant>WAFFLE_PLATFORM_WAYLAND</constant></term>
 135                 <listitem>
 136                   <para>
 137                     [Linux] Use EGL with the Wayland display server.
 138                   </para>
 139                 </listitem>
 140               </varlistentry>
 141               <varlistentry>
 142                 <term><constant>WAFFLE_PLATFORM_WGL</constant></term>
 143                 <listitem>
 144                   <para>
 145                     [Windows] Use WGL on Windows.
 146                   </para>
 147                 </listitem>
 148               </varlistentry>
 149               <varlistentry>
 150                 <term><constant>WAFFLE_PLATFORM_X11_EGL</constant></term>
 151                 <listitem>
 152                   <para>
 153                     [Linux] Use EGL with the X11 display server.
 154                   </para>
 155                 </listitem>
 156               </varlistentry>
 157
 158             </variablelist>
 159           </para>
 160         </listitem>
 161       </varlistentry>
 162
 163     </variablelist>
 164   </refsect1>
 165
 166   <refsect1>
 167     <title>Return Value</title>
 168     <xi:include href="common/return-value.xml"/>
 169   </refsect1>
 170
 171   <refsect1>
 172     <title>Errors</title>
 173
 174     <xi:include href="common/error-codes.xml"/>
 175
 176     <para>
 177       Listed are the errors specific to <function>waffle_init()</function>.
 178     </para>
 179
 180     <variablelist>
 181
 182       <varlistentry>
 183         <term><errorcode>WAFFLE_ERROR_ALREADY_INITIALIZED</errorcode></term>
 184         <listitem>
 185           <para>
 186             Waffle has already been initialized with a successful call to <function>waffle_init()</function>.
 187           </para>
 188         </listitem>
 189       </varlistentry>
 190
 191       <varlistentry>
 192         <term><errorcode>WAFFLE_ERROR_BAD_ATTRIBUTE</errorcode></term>
 193         <listitem>
 194           <para>
 195             An item in <parameter>attrib_list</parameter> is unrecognized or has an invalid value, or a required
 196             attribute is missing.
 197           </para>
 198         </listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><errorcode>WAFFLE_ERROR_BUILT_WITHOUT_SUPPORT</errorcode></term>
 203         <listitem>
 204           <para>
 205             Waffle was built without support for the requested attribute.
 206           </para>
 207         </listitem>
 208       </varlistentry>
 209
 210     </variablelist>
 211
 212   </refsect1>
 213
 214   <refsect1>
 215     <title>Example</title>
 216
 217     <para>
 218       Initialize waffle for X11/EGL.
 219     </para>
 220
 221     <programlisting>
 222 <![CDATA[
 223 #include <waffle.h>
 224
 225 static const int32_t init_attrib_list[] = {
 226     WAFFLE_PLATFORM, WAFFLE_PLATFORM_X11_EGL,
 227     0,
 228 };
 229
 230 int
 231 main()
 232 {
 233     bool ok = waffle_init(init_attrib_list);
 234     if (ok)
 235         return EXIT_SUCCESS;
 236     else
 237         return EXIT_FAILURE;
 238 }
 239 ]]>
 240     </programlisting>
 241   </refsect1>
 242
 243   <xi:include href="common/issues.xml"/>
 244
 245   <refsect1>
 246     <title>See Also</title>
 247     <para>
 248       <citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 249     </para>
 250   </refsect1>
 251
 252 </refentry>
 253
 254 <!--
 255 vim:tw=120 et ts=2 sw=2:
 256 -->