doc/reference/cogl/html/cogl-Blend-Strings.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <title>Material Blend Strings</title>
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
   7 <link rel="home" href="index.html" title="Cogl Reference Manual">
   8 <link rel="up" href="ch01.html" title="Cogl - a modern 3D graphics API">
   9 <link rel="prev" href="cogl-Textures.html" title="Textures">
  10 <link rel="next" href="cogl-Materials.html" title="Materials">
  11 <meta name="generator" content="GTK-Doc V1.18.1 (XML mode)">
  12 <link rel="stylesheet" href="style.css" type="text/css">
  13 </head>
  14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="2">
  16 <tr valign="middle">
  17 <td><a accesskey="p" href="cogl-Textures.html"><img src="left.png" width="24" height="24" border="0" alt="Prev"></a></td>
  18 <td><a accesskey="u" href="ch01.html"><img src="up.png" width="24" height="24" border="0" alt="Up"></a></td>
  19 <td><a accesskey="h" href="index.html"><img src="home.png" width="24" height="24" border="0" alt="Home"></a></td>
  20 <th width="100%" align="center">Cogl Reference Manual</th>
  21 <td><a accesskey="n" href="cogl-Materials.html"><img src="right.png" width="24" height="24" border="0" alt="Next"></a></td>
  22 </tr>
  23 <tr><td colspan="5" class="shortcuts">
  24                    |
  25                   <a href="#cogl-Blend-Strings.description" class="shortcut">Cogl Blend Strings</a>
  26 </td></tr>
  27 </table>
  28 <div class="refentry">
  29 <a name="cogl-Blend-Strings"></a><div class="titlepage"></div>
  30 <div class="refnamediv"><table width="100%"><tr>
  31 <td valign="top">
  32 <h2><span class="refentrytitle"><a name="cogl-Blend-Strings.top_of_page"></a>Material Blend Strings</span></h2>
  33 <p>Material Blend Strings — A simple syntax and grammar for describing blending and texture
  34 combining functions.</p>
  35 </td>
  36 <td valign="top" align="right"></td>
  37 </tr></table></div>
  38 <div class="refsect1">
  39 <a name="cogl-Blend-Strings.description"></a><h2>Cogl Blend Strings</h2>
  40 <p>
  41 Describing GPU blending and texture combining states is rather awkward to do
  42 in a consise but also readable fashion. Cogl helps by supporting
  43 string based descriptions using a simple syntax.
  44 </p>
  45 <div class="section">
  46 <div class="titlepage"><div><div><h4 class="title">
  47 <a name="id564361"></a>Some examples</h4></div></div></div>
  48 <p>Here is an example used for blending:</p>
  49 <pre class="programlisting">
  50 "RGBA = ADD (SRC_COLOR * (SRC_COLOR[A]), DST_COLOR * (1-SRC_COLOR[A]))"
  51 </pre>
  52 <p>In OpenGL terms this replaces glBlendFunc[Separate] and
  53 glBlendEquation[Separate]</p>
  54 <p>
  55 Actually in this case it's more verbose than the GL equivalent:
  56 </p>
  57 <pre class="programlisting">
  58 glBlendFunc (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA);
  59 </pre>
  60 <p>
  61 But unless you are familiar with OpenGL or refer to its API documentation
  62 you wouldn't know that the default function used by OpenGL is GL_FUNC_ADD
  63 nor would you know that the above arguments determine what the source color
  64 and destination color will be multiplied by before being adding.
  65 </p>
  66 <p>Here is an example used for texture combining:</p>
  67 <pre class="programlisting">
  68 "RGB = REPLACE (PREVIOUS)"
  69 "A = MODULATE (PREVIOUS, TEXTURE)"
  70 </pre>
  71 <p>
  72 In OpenGL terms this replaces glTexEnv, and the above example is equivalent
  73 to this OpenGL code:
  74 </p>
  75 <pre class="programlisting">
  76   glTexEnvi (GL_TEXTURE_ENV, GL_TEXTURE_ENV_MODE, GL_COMBINE);
  77   glTexEnvi (GL_TEXTURE_ENV, GL_COMBINE_RGB, GL_REPLACE);
  78   glTexEnvi (GL_TEXTURE_ENV, GL_SRC0_RGB, GL_PREVIOUS);
  79   glTexEnvi (GL_TEXTURE_ENV, GL_OPERAND0_RGB, GL_SRC_COLOR);
  80   glTexEnvi (GL_TEXTURE_ENV, GL_COMBINE_ALPHA, GL_MODULATE);
  81   glTexEnvi (GL_TEXTURE_ENV, GL_SRC0_ALPHA, GL_PREVIOUS);
  82   glTexEnvi (GL_TEXTURE_ENV, GL_OPERAND0_ALPHA, GL_SRC_COLOR);
  83   glTexEnvi (GL_TEXTURE_ENV, GL_SRC1_ALPHA, GL_TEXTURE);
  84   glTexEnvi (GL_TEXTURE_ENV, GL_OPERAND1_ALPHA, GL_SRC_COLOR);
  85 </pre>
  86 </div>
  87 <div class="section">
  88 <div class="titlepage"><div><div><h4 class="title">
  89 <a name="cogl-Blend-String-syntax"></a>Here's the syntax</h4></div></div></div>
  90 <pre class="programlisting">
  91 &lt;statement&gt;:
  92   &lt;channel-mask&gt;=&lt;function-name&gt;(&lt;arg-list&gt;)
  93
  94   You can either use a single statement with an RGBA channel-mask or you can use
  95   two statements; one with an A channel-mask and the other with an RGB
  96   channel-mask.
  97
  98 &lt;channel-mask&gt;:
  99   A or RGB or RGBA
 100
 101 &lt;function-name&gt;:
 102   [A-Za-z_]*
 103
 104 &lt;arg-list&gt;:
 105   &lt;arg&gt;,&lt;arg&gt;
 106   or &lt;arg&gt;
 107   or ""
 108
 109   I.e. functions may take 0 or more arguments
 110
 111 &lt;arg&gt;:
 112   &lt;color-source&gt;
 113   1 - &lt;color-source&gt;                : Only intended for texture combining
 114   &lt;color-source&gt; * ( &lt;factor&gt; )     : Only intended for blending
 115   0                                 : Only intended for blending
 116
 117   See the blending or texture combining sections for further notes and examples.
 118
 119 &lt;color-source&gt;:
 120   &lt;source-name&gt;[&lt;channel-mask&gt;]
 121   &lt;source-name&gt;
 122
 123   See the blending or texture combining sections for the list of source-names
 124   valid in each context.
 125
 126   If a channel mask is not given then the channel mask of the statement
 127   is assumed instead.
 128
 129 &lt;factor&gt;:
 130   0
 131   1
 132   &lt;color-source&gt;
 133   1-&lt;color-source&gt;
 134   SRC_ALPHA_SATURATE
 135 </pre>
 136 </div>
 137 </div>
 138 </div>
 139 <div class="footer">
 140 <hr>
 141           Generated by GTK-Doc V1.18.1</div>
 142 </body>
 143 </html>