upstream-man-pages/man2/glXUseXFont.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook MathML Module V1.1b1//EN"
   3               "http://www.oasis-open.org/docbook/xml/mathml/1.1CR1/dbmathml.dtd">
   4 <refentry id="glXUseXFont">
   5     <refmeta>
   6         <refmetainfo>
   7             <copyright>
   8                 <year>1991-2006</year>
   9                 <holder>Silicon Graphics, Inc.</holder>
  10             </copyright>
  11         </refmetainfo>
  12         <refentrytitle>glXUseXFont</refentrytitle>
  13         <manvolnum>3G</manvolnum>
  14     </refmeta>
  15     <refnamediv>
  16         <refname>glXUseXFont</refname>
  17         <refpurpose>create bitmap display lists from an X font</refpurpose>
  18     </refnamediv>
  19     <refsynopsisdiv><title>C Specification</title>
  20         <funcsynopsis>
  21             <funcprototype>
  22                 <funcdef>void <function>glXUseXFont</function></funcdef>
  23                 <paramdef>Font <parameter>font</parameter></paramdef>
  24                 <paramdef>int <parameter>first</parameter></paramdef>
  25                 <paramdef>int <parameter>count</parameter></paramdef>
  26                 <paramdef>int <parameter>listBase</parameter></paramdef>
  27             </funcprototype>
  28         </funcsynopsis>
  29     </refsynopsisdiv>
  30     <!-- eqn: ignoring delim $$ -->
  31     <refsect1 id="parameters"><title>Parameters</title>
  32         <variablelist>
  33         <varlistentry>
  34             <term><parameter>font</parameter></term>
  35             <listitem>
  36                 <para>
  37                     Specifies the font from which character glyphs are to be taken.
  38                 </para>
  39             </listitem>
  40         </varlistentry>
  41         <varlistentry>
  42             <term><parameter>first</parameter></term>
  43             <listitem>
  44                 <para>
  45                     Specifies the index of the first glyph to be taken.
  46                 </para>
  47             </listitem>
  48         </varlistentry>
  49         <varlistentry>
  50             <term><parameter>count</parameter></term>
  51             <listitem>
  52                 <para>
  53                     Specifies the number of glyphs to be taken.
  54                 </para>
  55             </listitem>
  56         </varlistentry>
  57         <varlistentry>
  58             <term><parameter>listBase</parameter></term>
  59             <listitem>
  60                 <para>
  61                     Specifies the index of the first display list to be generated.
  62                 </para>
  63             </listitem>
  64         </varlistentry>
  65         </variablelist>
  66     </refsect1>
  67     <refsect1 id="description"><title>Description</title>
  68         <para>
  69             <function>glXUseXFont</function> generates <parameter>count</parameter> display lists,
  70             named <parameter>listBase</parameter> through
  71             <inlineequation><mml:math>
  72                 <!-- eqn: listBase + count - 1:-->
  73                 <mml:mrow>
  74                     <mml:mi mathvariant="italic">listBase</mml:mi>
  75                     <mml:mo>+</mml:mo>
  76                     <mml:mi mathvariant="italic">count</mml:mi>
  77                     <mml:mo>-</mml:mo>
  78                     <mml:mn>1</mml:mn>
  79                 </mml:mrow>
  80             </mml:math></inlineequation>,
  81             each containing a single <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry> command.
  82             The parameters of the <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry> command of display list
  83             <inlineequation><mml:math>
  84                 <!-- eqn: listBase + i:-->
  85                 <mml:mrow>
  86                     <mml:mi mathvariant="italic">listBase</mml:mi>
  87                     <mml:mo>+</mml:mo>
  88                     <mml:mi mathvariant="italic">i</mml:mi>
  89                 </mml:mrow>
  90             </mml:math></inlineequation>
  91             are derived from glyph
  92             <inlineequation><mml:math>
  93                 <!-- eqn: first + i:-->
  94                 <mml:mrow>
  95                     <mml:mi mathvariant="italic">first</mml:mi>
  96                     <mml:mo>+</mml:mo>
  97                     <mml:mi mathvariant="italic">i</mml:mi>
  98                 </mml:mrow>
  99             </mml:math></inlineequation>.
 100             Bitmap parameters
 101             <inlineequation><mml:math><mml:mi mathvariant="italic">xorig</mml:mi></mml:math></inlineequation>,
 102             <inlineequation><mml:math><mml:mi mathvariant="italic">yorig</mml:mi></mml:math></inlineequation>,
 103             <inlineequation><mml:math><mml:mi mathvariant="italic">width</mml:mi></mml:math></inlineequation>,
 104             and
 105             <inlineequation><mml:math><mml:mi mathvariant="italic">height</mml:mi></mml:math></inlineequation>
 106             are computed from font metrics as
 107             <inlineequation><mml:math>
 108                 <!-- eqn: descent-1:-->
 109                 <mml:mrow>
 110                     <mml:mi mathvariant="italic">descent</mml:mi>
 111                     <mml:mo>-</mml:mo>
 112                     <mml:mn>1</mml:mn>
 113                 </mml:mrow>
 114             </mml:math></inlineequation>,
 115             <inlineequation><mml:math>
 116                 <!-- eqn: -lbearing:-->
 117                 <mml:mrow>
 118                     <mml:mo>-</mml:mo>
 119                     <mml:mi mathvariant="italic">lbearing</mml:mi>
 120                 </mml:mrow>
 121             </mml:math></inlineequation>,
 122             <inlineequation><mml:math>
 123                 <!-- eqn: rbearing - lbearing:-->
 124                 <mml:mrow>
 125                     <mml:mi mathvariant="italic">rbearing</mml:mi>
 126                     <mml:mo>-</mml:mo>
 127                     <mml:mi mathvariant="italic">lbearing</mml:mi>
 128                 </mml:mrow>
 129             </mml:math></inlineequation>,
 130             and
 131             <inlineequation><mml:math>
 132                 <!-- eqn: ascent+descent:-->
 133                 <mml:mrow>
 134                     <mml:mi mathvariant="italic">ascent</mml:mi>
 135                     <mml:mo>+</mml:mo>
 136                     <mml:mi mathvariant="italic">descent</mml:mi>
 137                 </mml:mrow>
 138             </mml:math></inlineequation>,
 139             respectively.
 140             <inlineequation><mml:math><mml:mi mathvariant="italic">xmove</mml:mi></mml:math></inlineequation>
 141             is taken from the glyph's
 142             <inlineequation><mml:math><mml:mi mathvariant="italic">width</mml:mi></mml:math></inlineequation>
 143             metric,
 144             and
 145             <inlineequation><mml:math><mml:mi mathvariant="italic">ymove</mml:mi></mml:math></inlineequation>
 146             is set to zero.
 147             Finally,
 148             the glyph's image is converted to the appropriate format for <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry>.
 149         </para>
 150         <para>
 151             Using <function>glXUseXFont</function> may be more efficient than accessing the X font and generating
 152             the display lists explicitly,
 153             both because the display lists are created on the server without requiring
 154             a round trip of the glyph data,
 155             and because the server may choose to delay the creation of each
 156             bitmap until it is accessed.
 157         </para>
 158         <para>
 159             Empty display lists are created for all glyphs that are requested and
 160             are not defined in <parameter>font</parameter>.
 161             <function>glXUseXFont</function> is ignored if there is no current GLX context.
 162         </para>
 163     </refsect1>
 164     <refsect1 id="errors"><title>Errors</title>
 165         <para>
 166             <constant>BadFont</constant> is generated if <parameter>font</parameter> is not a valid font.
 167         </para>
 168         <para>
 169             <constant>GLXBadContextState</constant> is generated if the current GLX context is
 170             in display-list construction mode.
 171         </para>
 172         <para>
 173             <constant>GLXBadCurrentWindow</constant> is generated if the drawable associated
 174             with the current context of the calling thread is a window, and that
 175             window is no longer valid.
 176         </para>
 177     </refsect1>
 178     <refsect1 id="seealso"><title>See Also</title>
 179         <para>
 180             <citerefentry><refentrytitle>glBitmap</refentrytitle></citerefentry>,
 181             <citerefentry><refentrytitle>glXMakeCurrent</refentrytitle></citerefentry>
 182         </para>
 183     </refsect1>
 184     <refsect1 id="Copyright"><title>Copyright</title>
 185         <para>
 186             Copyright <trademark class="copyright"></trademark> 1991-2006
 187             Silicon Graphics, Inc. This document is licensed under the SGI
 188             Free Software B License. For details, see
 189             <ulink url="http://oss.sgi.com/projects/FreeB/">http://oss.sgi.com/projects/FreeB/</ulink>.
 190         </para>
 191     </refsect1>
 192 </refentry>