diff options
Diffstat (limited to 'libs/cairo-1.16.0/doc/public/html/cairo-Version-Information.html')
| -rw-r--r-- | libs/cairo-1.16.0/doc/public/html/cairo-Version-Information.html | 377 |
1 files changed, 377 insertions, 0 deletions
diff --git a/libs/cairo-1.16.0/doc/public/html/cairo-Version-Information.html b/libs/cairo-1.16.0/doc/public/html/cairo-Version-Information.html new file mode 100644 index 0000000..f2d831d --- /dev/null +++ b/libs/cairo-1.16.0/doc/public/html/cairo-Version-Information.html @@ -0,0 +1,377 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> +<title>Version Information: Cairo: A Vector Graphics Library</title> +<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> +<link rel="home" href="index.html" title="Cairo: A Vector Graphics Library"> +<link rel="up" href="cairo-support.html" title="Utilities"> +<link rel="prev" href="cairo-Error-handling.html" title="Error handling"> +<link rel="next" href="cairo-Types.html" title="Types"> +<meta name="generator" content="GTK-Doc V1.27 (XML mode)"> +<link rel="stylesheet" href="style.css" type="text/css"> +</head> +<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> +<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle"> +<td width="100%" align="left" class="shortcuts"> +<a href="#" class="shortcut">Top</a><span id="nav_description"> <span class="dim">|</span> + <a href="#cairo-Version-Information.description" class="shortcut">Description</a></span> +</td> +<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td> +<td><a accesskey="u" href="cairo-support.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td> +<td><a accesskey="p" href="cairo-Error-handling.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td> +<td><a accesskey="n" href="cairo-Types.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td> +</tr></table> +<div class="refentry"> +<a name="cairo-Version-Information"></a><div class="titlepage"></div> +<div class="refnamediv"><table width="100%"><tr> +<td valign="top"> +<h2><span class="refentrytitle"><a name="cairo-Version-Information.top_of_page"></a>Version Information</span></h2> +<p>Version Information — Compile-time and run-time version checks.</p> +</td> +<td class="gallery_image" valign="top" align="right"></td> +</tr></table></div> +<div class="refsect1"> +<a name="cairo-Version-Information.functions"></a><h2>Functions</h2> +<div class="informaltable"><table class="informaltable" width="100%" border="0"> +<colgroup> +<col width="150px" class="functions_return"> +<col class="functions_name"> +</colgroup> +<tbody> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-ENCODE:CAPS" title="CAIRO_VERSION_ENCODE()">CAIRO_VERSION_ENCODE</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"> +<a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-STRINGIZE:CAPS" title="CAIRO_VERSION_STRINGIZE()">CAIRO_VERSION_STRINGIZE</a><span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type"> +<span class="returnvalue">int</span> +</td> +<td class="function_name"> +<a class="link" href="cairo-Version-Information.html#cairo-version" title="cairo_version ()">cairo_version</a> <span class="c_punctuation">()</span> +</td> +</tr> +<tr> +<td class="function_type">const <span class="returnvalue">char</span> * +</td> +<td class="function_name"> +<a class="link" href="cairo-Version-Information.html#cairo-version-string" title="cairo_version_string ()">cairo_version_string</a> <span class="c_punctuation">()</span> +</td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="cairo-Version-Information.other"></a><h2>Types and Values</h2> +<div class="informaltable"><table class="informaltable" width="100%" border="0"> +<colgroup> +<col width="150px" class="name"> +<col class="description"> +</colgroup> +<tbody> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="cairo-Version-Information.html#CAIRO-VERSION:CAPS" title="CAIRO_VERSION">CAIRO_VERSION</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-MAJOR:CAPS" title="CAIRO_VERSION_MAJOR">CAIRO_VERSION_MAJOR</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-MINOR:CAPS" title="CAIRO_VERSION_MINOR">CAIRO_VERSION_MINOR</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-MICRO:CAPS" title="CAIRO_VERSION_MICRO">CAIRO_VERSION_MICRO</a></td> +</tr> +<tr> +<td class="define_keyword">#define</td> +<td class="function_name"><a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-STRING:CAPS" title="CAIRO_VERSION_STRING">CAIRO_VERSION_STRING</a></td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect1"> +<a name="cairo-Version-Information.description"></a><h2>Description</h2> +<p>Cairo has a three-part version number scheme. In this scheme, we use +even vs. odd numbers to distinguish fixed points in the software +vs. in-progress development, (such as from git instead of a tar file, +or as a "snapshot" tar file as opposed to a "release" tar file).</p> +<div class="informalexample"><pre class="screen"> + _____ Major. Always 1, until we invent a new scheme. +/ ___ Minor. Even/Odd = Release/Snapshot (tar files) or Branch/Head (git) +| / _ Micro. Even/Odd = Tar-file/git +| | / +1.0.0 +</pre></div> +<p>Here are a few examples of versions that one might see.</p> +<div class="informalexample"><pre class="screen"> +Releases +-------- +1.0.0 - A major release +1.0.2 - A subsequent maintenance release +1.2.0 - Another major release + +Snapshots +--------- +1.1.2 - A snapshot (working toward the 1.2.0 release) + +In-progress development (eg. from git) +-------------------------------------- +1.0.1 - Development on a maintenance branch (toward 1.0.2 release) +1.1.1 - Development on head (toward 1.1.2 snapshot and 1.2.0 release) +</pre></div> +<div class="refsect2"> +<a name="id-1.6.4.5.6"></a><h3>Compatibility</h3> + +The API/ABI compatibility guarantees for various versions are as +follows. First, let's assume some cairo-using application code that is +successfully using the API/ABI "from" one version of cairo. Then let's +ask the question whether this same code can be moved "to" the API/ABI +of another version of cairo. + +Moving from a release to any later version (release, snapshot, +development) is always guaranteed to provide compatibility. + +Moving from a snapshot to any later version is not guaranteed to +provide compatibility, since snapshots may introduce new API that ends +up being removed before the next release. + +Moving from an in-development version (odd micro component) to any +later version is not guaranteed to provide compatibility. In fact, +there's not even a guarantee that the code will even continue to work +with the same in-development version number. This is because these +numbers don't correspond to any fixed state of the software, but +rather the many states between snapshots and releases. + +</div> +<hr> +<div class="refsect2"> +<a name="id-1.6.4.5.7"></a><h3>Examining the version</h3> + +Cairo provides the ability to examine the version at either +compile-time or run-time and in both a human-readable form as well as +an encoded form suitable for direct comparison. Cairo also provides the +macro <a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-ENCODE:CAPS" title="CAIRO_VERSION_ENCODE()"><code class="function">CAIRO_VERSION_ENCODE()</code></a> to perform the encoding. + +<div class="informalexample"><pre class="screen"> +Compile-time +------------ +<a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-STRING:CAPS" title="CAIRO_VERSION_STRING"><span class="type">CAIRO_VERSION_STRING</span></a> Human-readable +<a class="link" href="cairo-Version-Information.html#CAIRO-VERSION:CAPS" title="CAIRO_VERSION"><span class="type">CAIRO_VERSION</span></a> Encoded, suitable for comparison + +Run-time +-------- +<a class="link" href="cairo-Version-Information.html#cairo-version-string" title="cairo_version_string ()"><code class="function">cairo_version_string()</code></a> Human-readable +<a class="link" href="cairo-Version-Information.html#cairo-version" title="cairo_version ()"><code class="function">cairo_version()</code></a> Encoded, suitable for comparison +</pre></div> + +For example, checking that the cairo version is greater than or equal +to 1.0.0 could be achieved at compile-time or run-time as follows: + +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1 +2 +3 +4 +5 +6</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="gtkdoc ppc">##if CAIRO_VERSION >= CAIRO_VERSION_ENCODE(1, 0, 0)</span> +<span class="function">printf</span> <span class="gtkdoc opt">(</span><span class="string">"Compiling with suitable cairo version: %s</span><span class="gtkdoc esc">\n</span><span class="string">"</span><span class="gtkdoc opt">, %</span>CAIRO_VERSION_STRING<span class="gtkdoc opt">);</span> +<span class="gtkdoc ppc">##endif</span> + +<span class="keyword">if</span> <span class="gtkdoc opt">(</span><span class="function"><a href="cairo-Version-Information.html#cairo-version">cairo_version</a></span><span class="gtkdoc opt">() >=</span> <span class="function"><a href="cairo-Version-Information.html#CAIRO-VERSION-ENCODE:CAPS">CAIRO_VERSION_ENCODE</a></span><span class="gtkdoc opt">(</span><span class="number">1</span><span class="gtkdoc opt">,</span> <span class="number">0</span><span class="gtkdoc opt">,</span> <span class="number">0</span><span class="gtkdoc opt">))</span> + <span class="function">printf</span> <span class="gtkdoc opt">(</span><span class="string">"Running with suitable cairo version: %s</span><span class="gtkdoc esc">\n</span><span class="string">"</span><span class="gtkdoc opt">,</span> <span class="function"><a href="cairo-Version-Information.html#cairo-version-string">cairo_version_string</a></span> <span class="gtkdoc opt">());</span></pre></td> + </tr> + </tbody> + </table> +</div> + +</div> +</div> +<div class="refsect1"> +<a name="cairo-Version-Information.functions_details"></a><h2>Functions</h2> +<div class="refsect2"> +<a name="CAIRO-VERSION-ENCODE:CAPS"></a><h3>CAIRO_VERSION_ENCODE()</h3> +<pre class="programlisting">#define CAIRO_VERSION_ENCODE(major, minor, micro)</pre> +<p>This macro encodes the given cairo version into an integer. The numbers +returned by <a class="link" href="cairo-Version-Information.html#CAIRO-VERSION:CAPS" title="CAIRO_VERSION"><code class="literal">CAIRO_VERSION</code></a> and <a class="link" href="cairo-Version-Information.html#cairo-version" title="cairo_version ()"><code class="function">cairo_version()</code></a> are encoded using this macro. +Two encoded version numbers can be compared as integers. The encoding ensures +that later versions compare greater than earlier versions.</p> +<div class="refsect3"> +<a name="CAIRO-VERSION-ENCODE.parameters"></a><h4>Parameters</h4> +<div class="informaltable"><table class="informaltable" width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>major</p></td> +<td class="parameter_description"><p>the major component of the version number</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>minor</p></td> +<td class="parameter_description"><p>the minor component of the version number</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>micro</p></td> +<td class="parameter_description"><p>the micro component of the version number</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="CAIRO-VERSION-ENCODE.returns"></a><h4>Returns</h4> +<p> the encoded version.</p> +</div> +<p class="since">Since: 1.0</p> +</div> +<hr> +<div class="refsect2"> +<a name="CAIRO-VERSION-STRINGIZE:CAPS"></a><h3>CAIRO_VERSION_STRINGIZE()</h3> +<pre class="programlisting">#define CAIRO_VERSION_STRINGIZE(major, minor, micro)</pre> +<p>This macro encodes the given cairo version into an string. The numbers +returned by <a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-STRING:CAPS" title="CAIRO_VERSION_STRING"><code class="literal">CAIRO_VERSION_STRING</code></a> and <a class="link" href="cairo-Version-Information.html#cairo-version-string" title="cairo_version_string ()"><code class="function">cairo_version_string()</code></a> are encoded using this macro. +The parameters to this macro must expand to numerical literals.</p> +<div class="refsect3"> +<a name="CAIRO-VERSION-STRINGIZE.parameters"></a><h4>Parameters</h4> +<div class="informaltable"><table class="informaltable" width="100%" border="0"> +<colgroup> +<col width="150px" class="parameters_name"> +<col class="parameters_description"> +<col width="200px" class="parameters_annotations"> +</colgroup> +<tbody> +<tr> +<td class="parameter_name"><p>major</p></td> +<td class="parameter_description"><p>the major component of the version number</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>minor</p></td> +<td class="parameter_description"><p>the minor component of the version number</p></td> +<td class="parameter_annotations"> </td> +</tr> +<tr> +<td class="parameter_name"><p>micro</p></td> +<td class="parameter_description"><p>the micro component of the version number</p></td> +<td class="parameter_annotations"> </td> +</tr> +</tbody> +</table></div> +</div> +<div class="refsect3"> +<a name="CAIRO-VERSION-STRINGIZE.returns"></a><h4>Returns</h4> +<p> a string literal containing the version.</p> +</div> +<p class="since">Since: 1.8</p> +</div> +<hr> +<div class="refsect2"> +<a name="cairo-version"></a><h3>cairo_version ()</h3> +<pre class="programlisting"><span class="returnvalue">int</span> +cairo_version (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<p>Returns the version of the cairo library encoded in a single +integer as per <a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-ENCODE:CAPS" title="CAIRO_VERSION_ENCODE()"><code class="literal">CAIRO_VERSION_ENCODE</code></a>. The encoding ensures that +later versions compare greater than earlier versions.</p> +<p>A run-time comparison to check that cairo's version is greater than +or equal to version X.Y.Z could be performed as follows:</p> +<div class="informalexample"> + <table class="listing_frame" border="0" cellpadding="0" cellspacing="0"> + <tbody> + <tr> + <td class="listing_lines" align="right"><pre>1</pre></td> + <td class="listing_code"><pre class="programlisting"><span class="keyword">if</span> <span class="gtkdoc opt">(</span><span class="function"><a href="cairo-Version-Information.html#cairo-version">cairo_version</a></span><span class="gtkdoc opt">() >=</span> <span class="function"><a href="cairo-Version-Information.html#CAIRO-VERSION-ENCODE:CAPS">CAIRO_VERSION_ENCODE</a></span><span class="gtkdoc opt">(</span>X<span class="gtkdoc opt">,</span>Y<span class="gtkdoc opt">,</span>Z<span class="gtkdoc opt">)) {...}</span></pre></td> + </tr> + </tbody> + </table> +</div> + +<p>See also <a class="link" href="cairo-Version-Information.html#cairo-version-string" title="cairo_version_string ()"><code class="function">cairo_version_string()</code></a> as well as the compile-time +equivalents <a class="link" href="cairo-Version-Information.html#CAIRO-VERSION:CAPS" title="CAIRO_VERSION"><code class="literal">CAIRO_VERSION</code></a> and <a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-STRING:CAPS" title="CAIRO_VERSION_STRING"><code class="literal">CAIRO_VERSION_STRING</code></a>.</p> +<div class="refsect3"> +<a name="cairo-version.returns"></a><h4>Returns</h4> +<p> the encoded version.</p> +</div> +<p class="since">Since: 1.0</p> +</div> +<hr> +<div class="refsect2"> +<a name="cairo-version-string"></a><h3>cairo_version_string ()</h3> +<pre class="programlisting">const <span class="returnvalue">char</span> * +cairo_version_string (<em class="parameter"><code><span class="type">void</span></code></em>);</pre> +<p>Returns the version of the cairo library as a human-readable string +of the form "X.Y.Z".</p> +<p>See also <a class="link" href="cairo-Version-Information.html#cairo-version" title="cairo_version ()"><code class="function">cairo_version()</code></a> as well as the compile-time equivalents +<a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-STRING:CAPS" title="CAIRO_VERSION_STRING"><code class="literal">CAIRO_VERSION_STRING</code></a> and <a class="link" href="cairo-Version-Information.html#CAIRO-VERSION:CAPS" title="CAIRO_VERSION"><code class="literal">CAIRO_VERSION</code></a>.</p> +<div class="refsect3"> +<a name="cairo-version-string.returns"></a><h4>Returns</h4> +<p> a string containing the version.</p> +</div> +<p class="since">Since: 1.0</p> +</div> +</div> +<div class="refsect1"> +<a name="cairo-Version-Information.other_details"></a><h2>Types and Values</h2> +<div class="refsect2"> +<a name="CAIRO-VERSION:CAPS"></a><h3>CAIRO_VERSION</h3> +<pre class="programlisting">#define CAIRO_VERSION</pre> +<p>The version of cairo available at compile-time, encoded using +<a class="link" href="cairo-Version-Information.html#CAIRO-VERSION-ENCODE:CAPS" title="CAIRO_VERSION_ENCODE()"><code class="function">CAIRO_VERSION_ENCODE()</code></a>.</p> +<p class="since">Since: 1.0</p> +</div> +<hr> +<div class="refsect2"> +<a name="CAIRO-VERSION-MAJOR:CAPS"></a><h3>CAIRO_VERSION_MAJOR</h3> +<pre class="programlisting">#define CAIRO_VERSION_MAJOR USE_cairo_version_OR_cairo_version_string_INSTEAD +</pre> +<p>The major component of the version of cairo available at compile-time.</p> +<p class="since">Since: 1.0</p> +</div> +<hr> +<div class="refsect2"> +<a name="CAIRO-VERSION-MINOR:CAPS"></a><h3>CAIRO_VERSION_MINOR</h3> +<pre class="programlisting">#define CAIRO_VERSION_MINOR USE_cairo_version_OR_cairo_version_string_INSTEAD +</pre> +<p>The minor component of the version of cairo available at compile-time.</p> +<p class="since">Since: 1.0</p> +</div> +<hr> +<div class="refsect2"> +<a name="CAIRO-VERSION-MICRO:CAPS"></a><h3>CAIRO_VERSION_MICRO</h3> +<pre class="programlisting">#define CAIRO_VERSION_MICRO USE_cairo_version_OR_cairo_version_string_INSTEAD +</pre> +<p>The micro component of the version of cairo available at compile-time.</p> +<p class="since">Since: 1.0</p> +</div> +<hr> +<div class="refsect2"> +<a name="CAIRO-VERSION-STRING:CAPS"></a><h3>CAIRO_VERSION_STRING</h3> +<pre class="programlisting">#define CAIRO_VERSION_STRING</pre> +<p>A human-readable string literal containing the version of cairo available +at compile-time, in the form of "X.Y.Z".</p> +<p class="since">Since: 1.8</p> +</div> +</div> +</div> +<div class="footer"> +<hr>Generated by GTK-Doc V1.27</div> +</body> +</html>
\ No newline at end of file |