<!-- clanlib header begin -->
<HTML>
<HEAD>
<TITLE>CL_Canvas - ClanLib Game SDK</TITLE>
<STYLE TYPE="text/css"><!--
HTML BODY
{
font-family: verdana, helvetica, sans-serif;
font-size: 12px;
}
H1 { font-size: 22px; }
H2 { font-size: 18px; }
H3 { font-size: 16px; }
H4 { font-size: 14px; }
P { font-size: 12px; }
LI { font-size: 12px; }
--></STYLE>
</HEAD>
<body bgcolor=white text=black link=blue vlink=#800080>
<center>
<img src="http://clanlib.org/gfx/clanlib.png">
</center>
<!-- clanlib header end -->
<center>
<p>
<a href="http://clanlib.org/docs.html">Home</a> |
<a href="classes.html">All Classes</a> |
<a href="modules.html">Grouped Classes</a> |
<a href="index.html">Index</a> |
<a href="search.html">Search</a>
</p>
</center>
<h1>Class CL_Canvas</h1>
<p> Construct hardware accelerated (where available) off-screen canvas buffer. <a href="#description">More...</a></p>
<p>Derived from:
<i>none</i>
<br>
Derived by:
<i>none</i>
<br>Group: Display (Display 2D)</p>
<p>
#include <ClanLib/display.h>
<p>
<table border=0 width=100%>
</table>
<p><b>Construction:</b></p>
<table border=0 width=100%>
<tr><td width=30% valign=top><p><a href="CL_Canvas__CL_Canvas.html">CL_Canvas</a></p></td><td valign=top><p> Constructs canvas buffer.</p></td></tr></table>
<p><b>Attributes:</b></p>
<table border=0 width=100%>
<tr><td width=30% valign=top><p><a href="CL_Canvas__get_gc.html">get_gc</a></p></td><td valign=top><p> Returns the graphic context for the canvas.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_Canvas__get_pixeldata.html">get_pixeldata</a></p></td><td valign=top><p> Returns the contents of the canvas.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_Canvas__get_width.html">get_width</a></p></td><td valign=top><p> Returns the width of currently selected surface.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_Canvas__get_height.html">get_height</a></p></td><td valign=top><p> Returns the height of currently selected surface.</p></td></tr></table>
<p><b>Operations:</b></p>
<table border=0 width=100%>
<tr><td width=30% valign=top><p><a href="CL_Canvas__operator =.html">operator =</a></p></td><td valign=top><p> Copy assignment operator.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_Canvas__set_pixeldata.html">set_pixeldata</a></p></td><td valign=top><p> Set contents of canvas.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_Canvas__select_surface.html">select_surface</a></p></td><td valign=top><p> Sets the surface that canvas is currently drawing on.</p></td></tr><tr><td width=30% valign=top><p><a href="CL_Canvas__sync_surface.html">sync_surface</a></p></td><td valign=top><p> Forces syncronization of the contents between canvas and selected surface.</p></td></tr></table>
<a name="#description"><p><b>Detailed description:</b></p>
!group=Display/Display 2D!
!header=display.h!
<p>For the OpenGL target, this object represents an OpenGL "pbuffer". A pbuffer
is an off-screen OpenGL context that can function as hardware accelerated rendering
to a canvas.</p>
<p>To use CL_Canvas, first create an instance of CL_Canvas. Then load a surface into
the canvas. This will make ClanLib copy the contents of the surface (texture for GL)
to the canvas. After this rendering operations can be performed on the canvas.</p>
<p>If the surface selected into the canvas is drawn, ClanLib will automatically upload
the contents of the canvas back into the surface. Likewise if another surface is selected
into the canvas the surface will be updated.</p>
<p>It is recommended to limit the amount of canvas objects in the application. Every
canvas require construction of a new OpenGL context, and canvases consume frame buffer
memory.</p>
<p>In Windows a pbuffer can get 'lost', meaning that the operating system can suddenly
just use the memory for something else, without warning. Because of this
it is adviced to keep data in the canvas for as little time as possible - sync_surface()
can be used force uploading of the canvas' contents to the surface. Generally you do not
need to do this since drawing the surface will force such an upload, but if the surface
is not be drawn for some time, forcing an upload is a good idea.</p>
<p>If the pbuffer is lost, ClanLib will automatically try to reclaim the canvas and sync
it with the latest version stored in the surface (the texture). As long as the pbuffer is
lost, any drawing commands on the canvas will be silently ignored. This cannot guarantee
never loosing what is drawn to the canvas, but at least not everything will be completely
lost.</p>
<p>Example of usage:</p>
<p>
CL_Surface surface_foo("foo.png");<br>
CL_Surface surface_bar("bar.png");<br>
CL_Canvas canvas;<br>
canvas.select_surface(surface_foo);<br>
surface_bar.draw(5, 5, canvas.get_gc());<br>
canvas.get_gc()->draw_line(0, 0, 100, 100, CL_Color::yellow);<br>
canvas.sync_surface();
</p>
<!-- clanlib footer begin -->
<center><br><br><font color="#a0a0a0">
Questions or comments, write to the <a href="http://clanlib.org/contact.html">ClanLib mailing list</a>.
</font></center>
</body>
</html>
<!-- clanlib footer end -->
