<?xml version='1.0' encoding='UTF-8'?> 
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="cairo-Quartz-Surfaces">
<refmeta>
<refentrytitle role="top_of_page" id="cairo-Quartz-Surfaces.top_of_page">Quartz Surfaces</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>
  CAIRO Library
</refmiscinfo>
</refmeta>
<refnamediv>
<refname>Quartz Surfaces</refname>
<refpurpose>Rendering to Quartz surfaces</refpurpose>
</refnamediv>

<refsynopsisdiv id="cairo-Quartz-Surfaces.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>#define             <link linkend="CAIRO-HAS-QUARTZ-SURFACE:CAPS">CAIRO_HAS_QUARTZ_SURFACE</link>
<link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> *   <link linkend="cairo-quartz-surface-create">cairo_quartz_surface_create</link>         (<parameter><link linkend="cairo-format-t"><type>cairo_format_t</type></link> format</parameter>,
                                                         <parameter>unsigned <link linkend="int"><type>int</type></link> width</parameter>,
                                                         <parameter>unsigned <link linkend="int"><type>int</type></link> height</parameter>);
<link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> *   <link linkend="cairo-quartz-surface-create-for-cg-context">cairo_quartz_surface_create_for_cg_context</link>
                                                        (<parameter><link linkend="CGContextRef"><type>CGContextRef</type></link> cgContext</parameter>,
                                                         <parameter>unsigned <link linkend="int"><type>int</type></link> width</parameter>,
                                                         <parameter>unsigned <link linkend="int"><type>int</type></link> height</parameter>);
<link linkend="CGContextRef"><returnvalue>CGContextRef</returnvalue></link>        <link linkend="cairo-quartz-surface-get-cg-context">cairo_quartz_surface_get_cg_context</link> (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);
</synopsis>
</refsynopsisdiv>

<refsect1 id="cairo-Quartz-Surfaces.description" role="desc">
<title role="desc.title">Description</title>
<para>
The Quartz surface is used to render cairo graphics targeting the
Apple OS X Quartz rendering system.
</para>
</refsect1>
<refsect1 id="cairo-Quartz-Surfaces.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="CAIRO-HAS-QUARTZ-SURFACE:CAPS" role="macro" condition="since:1.6">
<title>CAIRO_HAS_QUARTZ_SURFACE</title>
<indexterm zone="CAIRO-HAS-QUARTZ-SURFACE:CAPS" role="1.6"><primary sortas="HAS_QUARTZ_SURFACE">CAIRO_HAS_QUARTZ_SURFACE</primary></indexterm>
<programlisting>#define CAIRO_HAS_QUARTZ_SURFACE 1
</programlisting>
<para>
Defined if the Quartz surface backend is available.
This macro can be used to conditionally compile backend-specific code.
</para><para role="since">Since 1.6</para></refsect2>
<refsect2 id="cairo-quartz-surface-create" role="function" condition="since:1.6">
<title>cairo_quartz_surface_create ()</title>
<indexterm zone="cairo-quartz-surface-create" role="1.6"><primary sortas="quartz_surface_create">cairo_quartz_surface_create</primary></indexterm>
<programlisting><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> *   cairo_quartz_surface_create         (<parameter><link linkend="cairo-format-t"><type>cairo_format_t</type></link> format</parameter>,
                                                         <parameter>unsigned <link linkend="int"><type>int</type></link> width</parameter>,
                                                         <parameter>unsigned <link linkend="int"><type>int</type></link> height</parameter>);</programlisting>
<para>
Creates a Quartz surface backed by a CGBitmap.  The surface is
created using the Device RGB (or Device Gray, for A8) color space.
All Cairo operations, including those that require software
rendering, will succeed on this surface.
</para><variablelist role="params">
<varlistentry><term><parameter>format</parameter>&#160;:</term>
<listitem><simpara>format of pixels in the surface to create</simpara></listitem></varlistentry>
<varlistentry><term><parameter>width</parameter>&#160;:</term>
<listitem><simpara>width of the surface, in pixels</simpara></listitem></varlistentry>
<varlistentry><term><parameter>height</parameter>&#160;:</term>
<listitem><simpara>height of the surface, in pixels</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the newly created surface.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.6</para></refsect2>
<refsect2 id="cairo-quartz-surface-create-for-cg-context" role="function" condition="since:1.6">
<title>cairo_quartz_surface_create_for_cg_context ()</title>
<indexterm zone="cairo-quartz-surface-create-for-cg-context" role="1.6"><primary sortas="quartz_surface_create_for_cg_context">cairo_quartz_surface_create_for_cg_context</primary></indexterm>
<programlisting><link linkend="cairo-surface-t"><returnvalue>cairo_surface_t</returnvalue></link> *   cairo_quartz_surface_create_for_cg_context
                                                        (<parameter><link linkend="CGContextRef"><type>CGContextRef</type></link> cgContext</parameter>,
                                                         <parameter>unsigned <link linkend="int"><type>int</type></link> width</parameter>,
                                                         <parameter>unsigned <link linkend="int"><type>int</type></link> height</parameter>);</programlisting>
<para>
Creates a Quartz surface that wraps the given CGContext.  The
CGContext is assumed to be in the standard Cairo coordinate space
(that is, with the origin at the upper left and the Y axis
increasing downward).  If the CGContext is in the Quartz coordinate
space (with the origin at the bottom left), then it should be
flipped before this function is called.  The flip can be accomplished
using a translate and a scale; for example:
</para>
<para>
<informalexample><programlisting>
CGContextTranslateCTM (cgContext, 0.0, height);
CGContextScaleCTM (cgContext, 1.0, -1.0);
</programlisting></informalexample>
</para>
<para>
All Cairo operations are implemented in terms of Quartz operations,
as long as Quartz-compatible elements are used (such as Quartz fonts).
</para><variablelist role="params">
<varlistentry><term><parameter>cgContext</parameter>&#160;:</term>
<listitem><simpara>the existing CGContext for which to create the surface</simpara></listitem></varlistentry>
<varlistentry><term><parameter>width</parameter>&#160;:</term>
<listitem><simpara>width of the surface, in pixels</simpara></listitem></varlistentry>
<varlistentry><term><parameter>height</parameter>&#160;:</term>
<listitem><simpara>height of the surface, in pixels</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the newly created Cairo surface.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.6</para></refsect2>
<refsect2 id="cairo-quartz-surface-get-cg-context" role="function" condition="since:1.6">
<title>cairo_quartz_surface_get_cg_context ()</title>
<indexterm zone="cairo-quartz-surface-get-cg-context" role="1.6"><primary sortas="quartz_surface_get_cg_context">cairo_quartz_surface_get_cg_context</primary></indexterm>
<programlisting><link linkend="CGContextRef"><returnvalue>CGContextRef</returnvalue></link>        cairo_quartz_surface_get_cg_context (<parameter><link linkend="cairo-surface-t"><type>cairo_surface_t</type></link> *surface</parameter>);</programlisting>
<para>
Returns the CGContextRef that the given Quartz surface is backed
by.
</para>
<para>
A call to <link linkend="cairo-surface-flush"><function>cairo_surface_flush()</function></link> is required before using the
CGContextRef to ensure that all pending drawing operations are
finished and to restore any temporary modification cairo has made
to its state. A call to <link linkend="cairo-surface-mark-dirty"><function>cairo_surface_mark_dirty()</function></link> is required
after the state or the content of the CGContextRef has been
modified.
</para><variablelist role="params">
<varlistentry><term><parameter>surface</parameter>&#160;:</term>
<listitem><simpara>the Cairo Quartz surface</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&#160;:</term><listitem><simpara>the CGContextRef for the given surface.</simpara></listitem></varlistentry>
</variablelist><para role="since">Since 1.6</para></refsect2>

</refsect1>
<refsect1 id="cairo-Quartz-Surfaces.see-also">
<title>See Also</title>
<link linkend="cairo-surface-t"><type>cairo_surface_t</type></link>
</refsect1>

</refentry>
