[cairo-commit] cairo/doc/reference/xml cairo_copy.xml,1.2,1.3 cairo_create.xml,1.2,1.3 cairo_destroy.xml,1.2,1.3 cairo_in_fill.xml,1.1,1.2 cairo_in_stroke.xml,1.1,1.2 cairo_reference.xml,1.2,1.3 cairo_restore.xml,1.2,1.3 cairo_save.xml,1.2,1.3 cairo_set_target_surface.xml,1.2,1.3 skeleton.xml,1.1,1.2

Thomas Hunger commit at pdx.freedesktop.org
Thu Oct 16 10:54:36 PDT 2003 

Committed by: tom

Update of /cvs/cairo/cairo/doc/reference/xml
In directory pdx:/tmp/cvs-serv21460/xml

Modified Files:
	cairo_copy.xml cairo_create.xml cairo_destroy.xml 
	cairo_in_fill.xml cairo_in_stroke.xml cairo_reference.xml 
	cairo_restore.xml cairo_save.xml cairo_set_target_surface.xml 
	skeleton.xml 
Log Message:
started to document from top to bottom.
most things are obvious


Index: cairo_copy.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_copy.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** cairo_copy.xml	16 Oct 2003 12:31:56 -0000	1.2
--- cairo_copy.xml	16 Oct 2003 17:54:34 -0000	1.3
***************
*** 1,3 ****
- 
  <refentry id="cairo_copy">
    <refmeta>
--- 1,2 ----
***************
*** 7,11 ****
    <refnamediv>
      <refname>cairo_copy</refname>
!     <refpurpose>some description</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
--- 6,10 ----
    <refnamediv>
      <refname>cairo_copy</refname>
!     <refpurpose>copy contents from one <link linkend="cairo_t">cairo_t</link> to another</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
***************
*** 16,20 ****
          <term><parameter>dest</parameter> :</term>
          <listitem>
!           <simpara>description</simpara>
          </listitem>
        </varlistentry>
--- 15,19 ----
          <term><parameter>dest</parameter> :</term>
          <listitem>
!           <simpara>an allocated <link linkend="cairo_t">cairo_t</link></simpara>
          </listitem>
        </varlistentry>
***************
*** 22,26 ****
          <term><parameter>src</parameter> :</term>
          <listitem>
!           <simpara>description</simpara>
          </listitem>
        </varlistentry>
--- 21,25 ----
          <term><parameter>src</parameter> :</term>
          <listitem>
!           <simpara><link linkend="cairo_t">cairo_t</link> to copy</simpara>
          </listitem>
        </varlistentry>
***************
*** 37,41 ****
--- 36,54 ----
          <primary/>
        </indexterm>
+       This function copies all state information from src to dest. That includes not yet drawn paths and font information.
+     </para>
+     <para>
+ The new <link linkend="cairo_t">cairo_t</link> will become owner of the target and clip surfaces by incrementing their refcount. But the surfaces will not be copied, that means operations on either src or dest will be painted onto the same surface.
+     </para>
+     <para>
+     Note that saved states on the stack can only be restored once. So if you have unclosed calls to <link linkend="cairo_save">cairo_save</link> before copying, calling <link linkend="cairo_restore">cairo_restore</link> on both, src and dest is invalid.
+     </para>
+   </refsect1>
+   <refsect1>
+     <title>See also</title>
+     <para>
+     cairo_clone 
      </para>
    </refsect1>
+ 
  </refentry>

Index: cairo_create.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_create.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** cairo_create.xml	16 Oct 2003 12:31:56 -0000	1.2
--- cairo_create.xml	16 Oct 2003 17:54:34 -0000	1.3
***************
*** 1,3 ****
- 
  <refentry id="cairo_create">
    <refmeta>
--- 1,2 ----
***************
*** 7,11 ****
    <refnamediv>
      <refname>cairo_create</refname>
!     <refpurpose>some description</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
--- 6,10 ----
    <refnamediv>
      <refname>cairo_create</refname>
!     <refpurpose>create a new <link linkend="cairo_t">cairo_t</link> object</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
***************
*** 30,33 ****
--- 29,33 ----
          <primary/>
        </indexterm>
+       This function creates a new <link linkend="cairo_t">cairo_t</link> with a reference count of one. Call <link linkend="cairo_destroy">cairo_destroy</link> to free the allocated resources.
      </para>
    </refsect1>

Index: cairo_destroy.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_destroy.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** cairo_destroy.xml	16 Oct 2003 12:31:56 -0000	1.2
--- cairo_destroy.xml	16 Oct 2003 17:54:34 -0000	1.3
***************
*** 1,3 ****
- 
  <refentry id="cairo_destroy">
    <refmeta>
--- 1,2 ----
***************
*** 7,11 ****
    <refnamediv>
      <refname>cairo_destroy</refname>
!     <refpurpose>some description</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
--- 6,10 ----
    <refnamediv>
      <refname>cairo_destroy</refname>
!     <refpurpose>free a <link linkend="cairo_t">cairo_t</link></refpurpose>
    </refnamediv>
    <refsynopsisdiv>
***************
*** 16,20 ****
          <term><parameter>cr</parameter> :</term>
          <listitem>
!           <simpara>description</simpara>
          </listitem>
        </varlistentry>
--- 15,19 ----
          <term><parameter>cr</parameter> :</term>
          <listitem>
!           <simpara>a <link linkend="cairo_t">cairo_t</link></simpara>
          </listitem>
        </varlistentry>
***************
*** 31,34 ****
--- 30,37 ----
          <primary/>
        </indexterm>
+       Decreases the reference of a a <link linkend="cairo_t">cairo_t</link>. If the refcount drops to zero, all associated resources will be freed.
+     </para>
+     <para>
+       Saved states on the stack which were not restored with <link linkend="cairo_restore">cairo_restore</link> will be destroyed, too.
      </para>
    </refsect1>

Index: cairo_in_fill.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_in_fill.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** cairo_in_fill.xml	15 Oct 2003 15:51:06 -0000	1.1
--- cairo_in_fill.xml	16 Oct 2003 17:54:34 -0000	1.2
***************
*** 16,20 ****
  </funcsynopsisinfo>
  <funcprototype>
!   <funcdef>void <function>cairo_in_fill</function></funcdef><paramdef>cairo_t <parameter>*cr</parameter></paramdef>
  <paramdef>double <parameter>x</parameter></paramdef>
  <paramdef>double <parameter>y</parameter></paramdef>
--- 16,20 ----
  </funcsynopsisinfo>
  <funcprototype>
!   <funcdef>void <function>cairo_in_fill</function></funcdef><paramdef><link linkend="cairo_t">cairo_t</link> <parameter>*cr</parameter></paramdef>
  <paramdef>double <parameter>x</parameter></paramdef>
  <paramdef>double <parameter>y</parameter></paramdef>

Index: cairo_in_stroke.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_in_stroke.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** cairo_in_stroke.xml	15 Oct 2003 15:51:06 -0000	1.1
--- cairo_in_stroke.xml	16 Oct 2003 17:54:34 -0000	1.2
***************
*** 16,20 ****
  </funcsynopsisinfo>
  <funcprototype>
!   <funcdef>void <function>cairo_in_stroke</function></funcdef><paramdef>cairo_t <parameter>*cr</parameter></paramdef>
  <paramdef>double <parameter>x</parameter></paramdef>
  <paramdef>double <parameter>y</parameter></paramdef>
--- 16,20 ----
  </funcsynopsisinfo>
  <funcprototype>
!   <funcdef>void <function>cairo_in_stroke</function></funcdef><paramdef><link linkend="cairo_t">cairo_t</link> <parameter>*cr</parameter></paramdef>
  <paramdef>double <parameter>x</parameter></paramdef>
  <paramdef>double <parameter>y</parameter></paramdef>

Index: cairo_reference.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_reference.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** cairo_reference.xml	16 Oct 2003 12:31:56 -0000	1.2
--- cairo_reference.xml	16 Oct 2003 17:54:34 -0000	1.3
***************
*** 1,3 ****
- 
  <refentry id="cairo_reference">
    <refmeta>
--- 1,2 ----
***************
*** 7,11 ****
    <refnamediv>
      <refname>cairo_reference</refname>
!     <refpurpose>some description</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
--- 6,10 ----
    <refnamediv>
      <refname>cairo_reference</refname>
!     <refpurpose>increase reference count of <link linkend="cairo_t">cairo_t</link></refpurpose>
    </refnamediv>
    <refsynopsisdiv>
***************
*** 16,20 ****
          <term><parameter>cr</parameter> :</term>
          <listitem>
!           <simpara>description</simpara>
          </listitem>
        </varlistentry>
--- 15,19 ----
          <term><parameter>cr</parameter> :</term>
          <listitem>
!           <simpara>a <link linkend="cairo_t">cairo_t</link></simpara>
          </listitem>
        </varlistentry>
***************
*** 31,34 ****
--- 30,34 ----
          <primary/>
        </indexterm>
+       When calling <function>cairo_reference</function> the reference count will be increased by one and the caller becomes owner of the <link linkend="cairo_t">cairo_t</link>. When the creator of the <link linkend="cairo_t">cairo_t</link> destroys the the object via <link linkend="cairo_destroy">cairo_destroy</link> the refcount will be decreased but the object will stay valid, since you are still owner of the object.
      </para>
    </refsect1>

Index: cairo_restore.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_restore.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** cairo_restore.xml	16 Oct 2003 12:31:56 -0000	1.2
--- cairo_restore.xml	16 Oct 2003 17:54:34 -0000	1.3
***************
*** 7,11 ****
    <refnamediv>
      <refname>cairo_restore</refname>
!     <refpurpose>some description</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
--- 7,11 ----
    <refnamediv>
      <refname>cairo_restore</refname>
!     <refpurpose>restore a saved state</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
***************
*** 31,34 ****
--- 31,35 ----
          <primary/>
        </indexterm>
+       This fucntion is the counterpart to <link linkend="cairo_save">cairo_save</link>. A saved state can be restored with cairo_restore. 
      </para>
    </refsect1>

Index: cairo_save.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_save.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** cairo_save.xml	16 Oct 2003 12:31:56 -0000	1.2
--- cairo_save.xml	16 Oct 2003 17:54:34 -0000	1.3
***************
*** 7,11 ****
    <refnamediv>
      <refname>cairo_save</refname>
!     <refpurpose>some description</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
--- 7,11 ----
    <refnamediv>
      <refname>cairo_save</refname>
!     <refpurpose>save current state</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
***************
*** 16,20 ****
          <term><parameter>cr</parameter> :</term>
          <listitem>
!           <simpara>description</simpara>
          </listitem>
        </varlistentry>
--- 16,20 ----
          <term><parameter>cr</parameter> :</term>
          <listitem>
!           <simpara>a <link linkend="cairo_t">cairo_t</link></simpara>
          </listitem>
        </varlistentry>
***************
*** 31,34 ****
--- 31,35 ----
          <primary/>
        </indexterm>
+       This function stores the complete state of a <link linkend="cairo_t">cairo_t</link>. It may then be changed in any way. The saved state can then be restored with <link linkend="cairo_restore">cairo_restore</link>. Calls to cairo_save may be nested to an arbitraty depth.
      </para>
    </refsect1>

Index: cairo_set_target_surface.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/cairo_set_target_surface.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** cairo_set_target_surface.xml	16 Oct 2003 12:31:56 -0000	1.2
--- cairo_set_target_surface.xml	16 Oct 2003 17:54:34 -0000	1.3
***************
*** 6,10 ****
    <refnamediv>
      <refname>cairo_set_target_surface</refname>
!     <refpurpose>some description</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
--- 6,10 ----
    <refnamediv>
      <refname>cairo_set_target_surface</refname>
!     <refpurpose>set surface for painting operations </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
***************
*** 15,19 ****
          <term><parameter>cr</parameter> :</term>
          <listitem>
!           <simpara>description</simpara>
          </listitem>
        </varlistentry>
--- 15,19 ----
          <term><parameter>cr</parameter> :</term>
          <listitem>
!           <simpara>a <link linkend="cairo_t">cairo_t</link></simpara>
          </listitem>
        </varlistentry>
***************
*** 21,25 ****
          <term><parameter>surface</parameter> :</term>
          <listitem>
!           <simpara>description</simpara>
          </listitem>
        </varlistentry>
--- 21,25 ----
          <term><parameter>surface</parameter> :</term>
          <listitem>
!           <simpara>an allocated <link linkend="cairo_surface_t">cairo_surface_t</link></simpara>
          </listitem>
        </varlistentry>
***************
*** 36,39 ****
--- 36,40 ----
          <primary/>
        </indexterm>
+ Selects  <varname>surfacee</varname> as the surface to draw on. If there already is a surface set, it will be substituted by <varname>surface</varname>.  It references  <varname>surface</varname>e to ensure that it will be calid at least until another surface was selected or the <link linkend="cairo_t">cairo_t</link> is destroyed.
      </para>
    </refsect1>

Index: skeleton.xml
===================================================================
RCS file: /cvs/cairo/cairo/doc/reference/xml/skeleton.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -C2 -d -r1.1 -r1.2
*** skeleton.xml	15 Oct 2003 15:51:06 -0000	1.1
--- skeleton.xml	16 Oct 2003 17:54:34 -0000	1.2
***************
*** 2,6 ****
  
  <refnamediv>
! <refname>##function##</refname>
  <refpurpose></refpurpose>
  </refnamediv>
--- 2,6 ----
  
  <refnamediv>
! <refname><link linkend="##function##">##function##</link></refname>
  <refpurpose></refpurpose>
  </refnamediv>
***************
*** 12,16 ****
  </funcsynopsisinfo>
  <funcprototype>
!   <funcdef>cairo_t *<function>##function##</function></funcdef>
    <paramdef>
    </paramdef>
--- 12,16 ----
  </funcsynopsisinfo>
  <funcprototype>
!   <funcdef><link linkend="cairo_t">cairo_t</link> *<function><link linkend="##function##">##function##</link></function></funcdef>
    <paramdef>
    </paramdef>
***************
*** 25,29 ****
  <indexterm><primary></primary></indexterm>
  
! <function>##function##</function> 
  </para>
  </refsect1>
--- 25,29 ----
  <indexterm><primary></primary></indexterm>
  
! <function><link linkend="##function##">##function##</link></function> 
  </para>
  </refsect1>

More information about the cairo-commit mailing list