<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
]>
<refentry id="GdkDrawContext">
<refmeta>
<refentrytitle role="top_of_page" id="GdkDrawContext.top_of_page">GdkDrawContext</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GDK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GdkDrawContext</refname>
<refpurpose>Base class for draw contexts</refpurpose>
</refnamediv>

<refsect1 id="GdkDrawContext.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GdkDisplay"><returnvalue>GdkDisplay</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gdk-draw-context-get-display">gdk_draw_context_get_display</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="GdkSurface"><returnvalue>GdkSurface</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gdk-draw-context-get-surface">gdk_draw_context_get_surface</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-draw-context-begin-frame">gdk_draw_context_begin_frame</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-draw-context-end-frame">gdk_draw_context_end_frame</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
</entry><entry role="function_name"><link linkend="gdk-draw-context-is-in-frame">gdk_draw_context_is_in_frame</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type">const <link linkend="cairo-region-t"><returnvalue>cairo_region_t</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gdk-draw-context-get-frame-region">gdk_draw_context_get_frame_region</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GdkDrawContext.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GdkDrawContext-struct">GdkDrawContext</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GdkDrawContext.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GdkDrawContext
        <phrase role="lineart">&#9500;&#9472;&#9472;</phrase> <link linkend="GdkGLContext">GdkGLContext</link>
        <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GdkVulkanContext">GdkVulkanContext</link>
</screen>
</refsect1>

<refsect1 id="GdkDrawContext.includes"><title>Includes</title><synopsis>#include &lt;gdk/gdk.h&gt;
</synopsis></refsect1>

<refsect1 id="GdkDrawContext.description" role="desc">
<title role="desc.title">Description</title>
<para><link linkend="GdkDrawContext"><type>GdkDrawContext</type></link> is the base object used by contexts implementing different
rendering methods, such as <link linkend="GdkGLContext"><type>GdkGLContext</type></link> or <link linkend="GdkVulkanContext"><type>GdkVulkanContext</type></link>. It provides
shared functionality between those contexts.</para>
<para>You will always interact with one of those subclasses.</para>
<para>A GdkDrawContext is always associated with a single toplevel surface.</para>

</refsect1>
<refsect1 id="GdkDrawContext.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gdk-draw-context-get-display" role="function">
<title>gdk_draw_context_get_display&#160;()</title>
<indexterm zone="gdk-draw-context-get-display"><primary>gdk_draw_context_get_display</primary></indexterm>
<programlisting language="C"><link linkend="GdkDisplay"><returnvalue>GdkDisplay</returnvalue></link>&#160;*
gdk_draw_context_get_display (<parameter><link linkend="GdkDrawContext"><type>GdkDrawContext</type></link> *context</parameter>);</programlisting>
<para>Retrieves the <link linkend="GdkDisplay"><type>GdkDisplay</type></link> the <parameter>context</parameter>
 is created for</para>
<refsect3 id="gdk-draw-context-get-display.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkDrawContext"><type>GdkDrawContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-draw-context-get-display.returns" role="returns">
<title>Returns</title>
<para>a <link linkend="GdkDisplay"><type>GdkDisplay</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gdk-draw-context-get-surface" role="function">
<title>gdk_draw_context_get_surface&#160;()</title>
<indexterm zone="gdk-draw-context-get-surface"><primary>gdk_draw_context_get_surface</primary></indexterm>
<programlisting language="C"><link linkend="GdkSurface"><returnvalue>GdkSurface</returnvalue></link>&#160;*
gdk_draw_context_get_surface (<parameter><link linkend="GdkDrawContext"><type>GdkDrawContext</type></link> *context</parameter>);</programlisting>
<para>Retrieves the <link linkend="GdkSurface"><type>GdkSurface</type></link> used by the <parameter>context</parameter>
.</para>
<refsect3 id="gdk-draw-context-get-surface.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkDrawContext"><type>GdkDrawContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-draw-context-get-surface.returns" role="returns">
<title>Returns</title>
<para>a <link linkend="GdkSurface"><type>GdkSurface</type></link> or <link linkend="NULL:CAPS"><literal>NULL</literal></link>. </para>
<para><emphasis role="annotation">[<acronym>nullable</acronym>][<acronym>transfer none</acronym>]</emphasis></para>
</refsect3></refsect2>
<refsect2 id="gdk-draw-context-begin-frame" role="function">
<title>gdk_draw_context_begin_frame&#160;()</title>
<indexterm zone="gdk-draw-context-begin-frame"><primary>gdk_draw_context_begin_frame</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_draw_context_begin_frame (<parameter><link linkend="GdkDrawContext"><type>GdkDrawContext</type></link> *context</parameter>,
                              <parameter>const <link linkend="cairo-region-t"><type>cairo_region_t</type></link> *region</parameter>);</programlisting>
<para>Indicates that you are beginning the process of redrawing <parameter>region</parameter>

on the <parameter>context</parameter>
's surface.</para>
<para>Calling this function begins a drawing operation using <parameter>context</parameter>
 on the
surface that <parameter>context</parameter>
 was created from. The actual requirements and
guarantees for the drawing operation vary for different implementations
of drawing, so a <link linkend="GdkCairoContext"><type>GdkCairoContext</type></link> and a <link linkend="GdkGLContext"><type>GdkGLContext</type></link> need to be treated
differently.</para>
<para>A call to this function is a requirement for drawing and must be followed
by a call to <link linkend="gdk-draw-context-end-frame"><function>gdk_draw_context_end_frame()</function></link>, which will complete the
drawing operation and ensure the contents become visible on screen.</para>
<para>Note that the <parameter>region</parameter>
 passed to this function is the minimum region that
needs to be drawn and depending on implementation, windowing system and
hardware in use, it might be necessary to draw a larger region. Drawing
implementation must use <link linkend="gdk-draw-context-get-frame-region"><function>gdk_draw_context_get_frame_region()</function></link> to query the
region that must be drawn.</para>
<para>When using GTK+, the widget system automatically places calls to
<link linkend="gdk-draw-context-begin-frame"><function>gdk_draw_context_begin_frame()</function></link> and <link linkend="gdk-draw-context-end-frame"><function>gdk_draw_context_end_frame()</function></link> via the
use of <link linkend="GskRenderers"><type>GskRenderers</type></link>, so application code does not need to call these
functions explicitly.</para>
<refsect3 id="gdk-draw-context-begin-frame.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>the context used to draw the frame</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>region</para></entry>
<entry role="parameter_description"><para>minimum region that should be drawn</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gdk-draw-context-end-frame" role="function">
<title>gdk_draw_context_end_frame&#160;()</title>
<indexterm zone="gdk-draw-context-end-frame"><primary>gdk_draw_context_end_frame</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gdk_draw_context_end_frame (<parameter><link linkend="GdkDrawContext"><type>GdkDrawContext</type></link> *context</parameter>);</programlisting>
<para>Ends a drawing operation started with <link linkend="gdk-draw-context-begin-frame"><function>gdk_draw_context_begin_frame()</function></link>
and makes the drawing available on screen. See that function for more
details about drawing.</para>
<para>When using a <link linkend="GdkGLContext"><type>GdkGLContext</type></link>, this function may call <literal><link linkend="glFlush"><function>glFlush()</function></link></literal>
implicitly before returning; it is not recommended to call <literal><link linkend="glFlush"><function>glFlush()</function></link></literal>
explicitly before calling this function.</para>
<refsect3 id="gdk-draw-context-end-frame.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkDrawContext"><type>GdkDrawContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gdk-draw-context-is-in-frame" role="function">
<title>gdk_draw_context_is_in_frame&#160;()</title>
<indexterm zone="gdk-draw-context-is-in-frame"><primary>gdk_draw_context_is_in_frame</primary></indexterm>
<programlisting language="C"><link linkend="gboolean"><returnvalue>gboolean</returnvalue></link>
gdk_draw_context_is_in_frame (<parameter><link linkend="GdkDrawContext"><type>GdkDrawContext</type></link> *context</parameter>);</programlisting>
<para>Returns <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if <parameter>context</parameter>
 is in the process of drawing to its surface
after a call to <link linkend="gdk-draw-context-begin-frame"><function>gdk_draw_context_begin_frame()</function></link> and not yet having called
<link linkend="gdk-draw-context-end-frame"><function>gdk_draw_context_end_frame()</function></link>.
In this situation, drawing commands may be effecting the contents of a
<parameter>context</parameter>
's surface.</para>
<refsect3 id="gdk-draw-context-is-in-frame.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkDrawContext"><type>GdkDrawContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-draw-context-is-in-frame.returns" role="returns">
<title>Returns</title>
<para> <link linkend="TRUE:CAPS"><literal>TRUE</literal></link> if the context is between <link linkend="gdk-draw-context-begin-frame"><function>gdk_draw_context_begin_frame()</function></link>
and <link linkend="gdk-draw-context-end-frame"><function>gdk_draw_context_end_frame()</function></link> calls.</para>
</refsect3></refsect2>
<refsect2 id="gdk-draw-context-get-frame-region" role="function">
<title>gdk_draw_context_get_frame_region&#160;()</title>
<indexterm zone="gdk-draw-context-get-frame-region"><primary>gdk_draw_context_get_frame_region</primary></indexterm>
<programlisting language="C">const <link linkend="cairo-region-t"><returnvalue>cairo_region_t</returnvalue></link>&#160;*
gdk_draw_context_get_frame_region (<parameter><link linkend="GdkDrawContext"><type>GdkDrawContext</type></link> *context</parameter>);</programlisting>
<para>Retrieves the region that is currently in the process of being repainted.</para>
<para>After a call to <link linkend="gdk-draw-context-begin-frame"><function>gdk_draw_context_begin_frame()</function></link> this function will return
a union of the region passed to that function and the area of the surface
that the <parameter>context</parameter>
 determined needs to be repainted.</para>
<para>If <parameter>context</parameter>
 is not in between calls to <link linkend="gdk-draw-context-begin-frame"><function>gdk_draw_context_begin_frame()</function></link> and
<link linkend="gdk-draw-context-end-frame"><function>gdk_draw_context_end_frame()</function></link>, <link linkend="NULL:CAPS"><literal>NULL</literal></link> will be returned.</para>
<refsect3 id="gdk-draw-context-get-frame-region.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>context</para></entry>
<entry role="parameter_description"><para>a <link linkend="GdkDrawContext"><type>GdkDrawContext</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gdk-draw-context-get-frame-region.returns" role="returns">
<title>Returns</title>
<para>a Cairo region or <link linkend="NULL:CAPS"><literal>NULL</literal></link> if not drawing
a frame. </para>
<para><emphasis role="annotation">[<acronym>transfer none</acronym>][<acronym>nullable</acronym>]</emphasis></para>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GdkDrawContext.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GdkDrawContext-struct" role="struct">
<title>GdkDrawContext</title>
<indexterm zone="GdkDrawContext-struct"><primary>GdkDrawContext</primary></indexterm>
<programlisting language="C">typedef struct _GdkDrawContext GdkDrawContext;</programlisting>
<para>The GdkDrawContext struct contains only private fields and should not
be accessed directly.</para>
</refsect2>

</refsect1>

</refentry>
