man/waffle_display.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_display"
  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_display</refentrytitle>
  20     <manvolnum>3</manvolnum>
  21   </refmeta>
  22
  23   <refnamediv>
  24     <refname>waffle_display</refname>
  25     <refname>waffle_display_connect</refname>
  26     <refname>waffle_display_disconnect</refname>
  27     <refname>waffle_display_supports_context_api</refname>
  28     <refname>waffle_display_get_native</refname>
  29     <refpurpose>class <classname>waffle_display</classname></refpurpose>
  30   </refnamediv>
  31
  32   <refentryinfo>
  33     <title>Waffle Manual</title>
  34     <productname>waffle</productname>
  35     <xi:include href="common/author-lina.versace.xml"/>
  36     <xi:include href="common/copyright.xml"/>
  37     <xi:include href="common/legalnotice.xml"/>
  38   </refentryinfo>
  39
  40   <refsynopsisdiv>
  41
  42     <funcsynopsis language="C">
  43
  44       <funcsynopsisinfo>
  45 #include &lt;waffle.h&gt;
  46
  47 struct waffle_display;
  48       </funcsynopsisinfo>
  49
  50       <funcprototype>
  51         <funcdef>struct waffle_display* <function>waffle_display_connect</function></funcdef>
  52         <paramdef>const char* <parameter>name</parameter></paramdef>
  53       </funcprototype>
  54
  55       <funcprototype>
  56         <funcdef>bool <function>waffle_display_disconnect</function></funcdef>
  57         <paramdef>struct waffle_display *<parameter>self</parameter></paramdef>
  58       </funcprototype>
  59
  60       <funcprototype>
  61         <funcdef>bool <function>waffle_display_supports_context_api</function></funcdef>
  62         <paramdef>struct waffle_display *<parameter>self</parameter></paramdef>
  63         <paramdef>int32_t <parameter>context_api</parameter></paramdef>
  64       </funcprototype>
  65
  66       <funcprototype>
  67         <funcdef>union waffle_native_display* <function>waffle_display_get_native</function></funcdef>
  68         <paramdef>struct waffle_display *<parameter>self</parameter></paramdef>
  69       </funcprototype>
  70
  71     </funcsynopsis>
  72   </refsynopsisdiv>
  73
  74   <refsect1>
  75     <title>Description</title>
  76
  77     <variablelist>
  78
  79       <varlistentry>
  80         <term><type>struct waffle_display</type></term>
  81         <listitem>
  82           <para>
  83             An opaque type.
  84           </para>
  85         </listitem>
  86       </varlistentry>
  87
  88       <varlistentry>
  89         <term><function>waffle_display_connect()</function></term>
  90         <listitem>
  91           <para>
  92             Connect to a display. The interpretation of <parameter>name</parameter> differs according to the platform
  93             given to <citerefentry><refentrytitle><function>waffle_init</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>.
  94           </para>
  95           <para>
  96             On Android, CGL and WGL <parameter>name</parameter> is ignored.
  97           </para>
  98           <para>
  99             On the X11 platforms, GLX and X11/EGL, the function connects to the X11 display with the given
 100             <parameter>name</parameter>. If <parameter>name</parameter> is null, then it uses the value of the
 101             environment variable <envar>DISPLAY</envar>.
 102           </para>
 103           <para>
 104             On Wayland, the function connects to the Wayland display with the given name. If <parameter>name</parameter> is null, then it
 105             uses the value of the environment variable <envar>WAYLAND_DISPLAY</envar>.
 106           </para>
 107           <para>
 108             On GBM, the function opens the device at the filepath <parameter>name</parameter>.
 109
 110             If <parameter>name</parameter> is NULL, then the function uses the value of environment variable
 111             <envar>WAFFLE_GBM_DEVICE</envar>.
 112
 113             If <parameter>name</parameter> is null and <envar>WAFFLE_GBM_DEVICE</envar> is unset, then the function
 114             iterates using libdrm through the set of card devices in the drm subsystem, which are usually located in
 115             <filename>/dev/dri</filename>, and attempts to open each in turn with <code>open(O_RDWR | O_CLOEXEC)</code>
 116             until successful.
 117           </para>
 118         </listitem>
 119       </varlistentry>
 120
 121       <varlistentry>
 122         <term><function>waffle_display_disconnect()</function></term>
 123         <listitem>
 124           <para>
 125             Disconnect from the <type>waffle_display</type> and release it's memory. All pointers to waffle objects that
 126             were created with the display become invalid.
 127           </para>
 128         </listitem>
 129       </varlistentry>
 130
 131       <varlistentry>
 132         <term><function>waffle_display_supports_context_api()</function></term>
 133         <listitem>
 134           <para>
 135             Check if the display is capable of creating
 136             a <citerefentry><refentrytitle><function>waffle_context</function></refentrytitle><manvolnum>3</manvolnum></citerefentry> with
 137             the given <parameter>context_api</parameter>. See
 138             <citerefentry><refentrytitle><function>waffle_config</function></refentrytitle><manvolnum>3</manvolnum></citerefentry> for
 139             choices of <parameter>context_api</parameter> and expectations for each platform.
 140           </para>
 141         </listitem>
 142       </varlistentry>
 143
 144       <varlistentry>
 145         <term><function>waffle_display_get_native()</function></term>
 146         <listitem>
 147           <para>
 148             Get the display's underlying native objects. Use
 149             <citerefentry><refentrytitle><function>free</function></refentrytitle><manvolnum>3</manvolnum></citerefentry> to deallocate the
 150             returned pointer.
 151             See <citerefentry><refentrytitle><function>waffle_native</function></refentrytitle><manvolnum>3</manvolnum></citerefentry>
 152             for the definition of <type>union waffle_native_display</type>.
 153           </para>
 154         </listitem>
 155       </varlistentry>
 156
 157     </variablelist>
 158   </refsect1>
 159
 160   <refsect1>
 161     <title>Return Value</title>
 162     <xi:include href="common/return-value.xml"/>
 163   </refsect1>
 164
 165   <refsect1>
 166     <title>Errors</title>
 167
 168     <xi:include href="common/error-codes.xml"/>
 169
 170     <para>
 171       No errors are specific to any of the <type>waffle_display</type> functions.
 172     </para>
 173   </refsect1>
 174
 175   <xi:include href="common/issues.xml"/>
 176
 177   <refsect1>
 178     <title>See Also</title>
 179     <para>
 180       <citerefentry><refentrytitle>waffle</refentrytitle><manvolnum>7</manvolnum></citerefentry>
 181     </para>
 182   </refsect1>
 183
 184 </refentry>
 185
 186 <!--
 187 vim:tw=120 et ts=2 sw=2:
 188 -->