summaryrefslogtreecommitdiff
path: root/html/en/guide.html
diff options
context:
space:
mode:
authorscuri <scuri>2008-10-17 06:10:33 +0000
committerscuri <scuri>2008-10-17 06:10:33 +0000
commit7b52cc13af4e85f1ca2deb6b6c77de9c95ea0dcf (patch)
treed0857278bde2eff784227c57dcaf930346ceb7ac /html/en/guide.html
First commit - moving from LuaForge to SourceForge
Diffstat (limited to 'html/en/guide.html')
-rw-r--r--html/en/guide.html161
1 files changed, 161 insertions, 0 deletions
diff --git a/html/en/guide.html b/html/en/guide.html
new file mode 100644
index 0000000..e6d393c
--- /dev/null
+++ b/html/en/guide.html
@@ -0,0 +1,161 @@
+<!doctype HTML PUBLIC "-//IETF//DTD HTML//EN">
+<html xmlns:v="urn:schemas-microsoft-com:vml" xmlns:o="urn:schemas-microsoft-com:office:office">
+
+<head>
+<meta http-equiv="Content-Language" content="en-us">
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+
+<title>Guide</title>
+<link rel="stylesheet" type="text/css" href="../style.css">
+<style type="text/css">
+.style2 {
+ color: #008000;
+}
+.style3 {
+ color: #FF0000;
+}
+.style4 {
+ color: #0000FF;
+}
+</style>
+</head>
+
+<body>
+
+<h1>Guide</h1>
+<h3><a name="start">Getting Started</a></h3>
+
+ <p>The CD library is a basic graphic library (GL). In a GL paradigm you use <strong>primitives</strong>, which have
+ <strong>attributes</strong>, to draw on a <strong>canvas</strong>. All the library functions reflect this paradigm.</p>
+ <p>The <strong>canvas</strong> is the basic element. It can have several forms: a paper, a video monitor, a graphic
+ file format, etc. The virtual drawing surface where the canvas exists is represented by a <strong>driver</strong>.
+ Only the driver knows how to draw on its surface. The user does not use the driver directly, but only the canvas.</p>
+ <p>To make the library simple we use the concept of an active canvas, over which all the primitives are drawn. This
+ also allows the use of an expansion mechanism using function tables. Unfortunately if a function is called without an
+ active canvas a memory invasion will occur. On the other hand, the mechanism allows the library to be expanded with
+ new drivers without limits.</p>
+ <p>The <strong>attributes</strong> are also separated from the primitives. They reside in the canvas in a state
+ mechanism. If you change the attribute's state in the canvas all the primitives drawn after that canvas and that
+ depend on the attribute will be drawn in a different way.</p>
+ <p>The set of <strong>primitives</strong> is very small but complete enough to compose a GL. Some primitives are
+ system dependent for performance reasons. Some drivers (window and device based) use system functions to optimally
+ implement the primitives. Sometimes this implies in a in small different behavior of some functions. Also some
+ primitives do not make sense in some drivers, like server images in file-based drivers.</p>
+ <p>The set of available functions is such that it can be implemented in most drivers. Some drivers have sophisticated
+ resources, which cannot be implemented in other drivers but can be made available using a generic attribute mecanism.
+ </p>
+
+<h3><a name="buildapp">Building Applications</a></h3>
+
+ <p>All the CD functions are declared in the <tt>cd.h</tt> header file; World Coordinate functions are declared in the
+ <tt>wd.h</tt> header file; and each driver has a correspondent header file that must be included to create a canvas.
+ It is important to include each driver header <u>after</u> the inclusion of the <tt>cd.h</tt> header file.</p>
+ <p>To link the application you must add the <b>cd.lib/libcd.a/libcd.so</b> and <b>
+ freetype6.lib/libfreetype.a/libfreetype.so </b> libraries to the linker options. If you use
+ an IUP Canvas then you must also link with the <b>iupcd.lib/libiupcd.a/libiupcd.so</b> library
+ available in the IUP distribution.</p>
+ <p>In UNIX, CD uses the Xlib (X11) libraries. To link an application in UNIX, add also the &quot;-lX11&quot; option in the linker call.</p>
+ <p>The download files list includes the <a href="download_tips.html">Tecgraf/PUC-Rio Library
+ Download Tips</a> document, with a description of all the available binaries.</p>
+
+<h3 align="left"><a name="buildlib">Building the Library</a> </h3>
+
+<p>In the Downloads you will ne able to find pre-compiled binaries for many
+platforms, all those binaries were built using Tecmake. Tecmake is a command line multi compiler build tool
+based on GNU make, available at
+ <a target="_blank" href="http://www.tecgraf.puc-rio.br/tecmake">http://www.tecgraf.puc-rio.br/tecmake</a>. Tecmake is
+ used by all the Tecgraf libraries and many applications.</p>
+<p>In UNIX, you do not need to install Tecmake, a compact version of Tecmake for
+UNIX is already included in the source code package. Just type &quot;make&quot; in the
+command line on the &quot;src&quot; folder and all libraries and executables will be
+build.
+</p>
+<p>In Windows, the easiest way to build everything is to install the Tecmake tool into your system. It is easy and helps a lot.
+ The Tecmake configuration files (*.mak) available at the &quot;src&quot; folder are very easy to understand also.
+Also there are files named
+<i>make_uname.bat</i> that build the libraries using <b>Tecmake</b>. To build for Windows using
+ Visual C 7.0 (2005) for example, just execute <i>&quot;make_uname vc7&quot;</i> , or the
+DLLs with Visual C++ 9 (2008) type <i>&quot;make_uname dll9&quot;</i>. The Visual
+Studio workspaces with the respective projects available in the source package
+is for debugging purposes only.</p>
+<p>Make sure you have all the dependencies for the library you want installed,
+see the documentation bellow.</p>
+<p>If you are going to build all the libraries,
+the makefiles and projects expect the following directory tree:</p>
+<pre>\mylibs\
+ cd\
+ im\
+ lua5.1\</pre>
+<h4>Libraries Dependencies</h4>
+<pre>cd -&gt; <strong><span class="style4">gdi32</span></strong> <strong><span class="style4">user32</span></strong> <strong><span class="style4">comdlg32</span></strong> (system - Windows)
+ -&gt; <strong><span class="style4">X11</span></strong> (system - UNIX)
+ -&gt; <strong><span class="style2">FreeType</span></strong> (included as separate library)
+cdgdiplus -&gt; cd
+ -&gt; <strong><span class="style4">gdiplus</span></strong> (system - Windows)
+cdxrender -&gt; cd
+ -&gt; <strong><span class="style4">Xrender</span></strong> <strong><span class="style4">Xft</span></strong> (system - UNIX)
+cdpdf -&gt; <strong><span class="style2">pdflib</span></strong> (included as separate library)
+cdlua51 -&gt; cd
+ -&gt; <strong><span class="style3">lua5.1</span></strong>
+cdluaim51 -&gt; cdlua51
+ -&gt; <strong><span class="style3">imlua51</span></strong>
+cdluapdf51 -&gt; cdlua51
+ -&gt; cdpdf</pre>
+<p>As a general rule (excluding system dependencies and included third party
+libraries): CD has NO external dependencies, and CDLua depends on Lua and IMLua.
+Just notice that not all CDLua libraries depend on IMLua.</p>
+
+<h3><a name="Environment">Environment Variables</a></h3>
+
+ <p><font face="Courier New"><b>CDDIR</b></font> - This environment variable is used by some drivers to locate useful
+ data files, such as font definition files. It contains the directory path without the final slash.<br>
+ <font face="Courier New"><b>CD_QUIET</b></font> - In UNIX, if this variable is defined, it does not show the library's
+ version info on <em>sdtout</em>.<br>
+ <font face="Courier New"><b>CD_</b></font><b><font face="Courier New">XERROR</font></b> - In UNIX, if this variable is
+ defined, it will show the X-Windows error messages on <em>sdterr</em>.</p>
+
+<h3><a name="NewDriver">Implementing a Driver</a></h3>
+
+ <p>The best way to implement a new driver is based on an existing one. For this reason, we provide
+ a code of the
+ simplest driver possible, see <a href="../download/cdxx.h">CDXX.H</a> and <a href="../download/cdxx.c">CDXX.C</a>.
+ But first you should read the <a href="internal.html">Internal Architecture</a>.</p>
+
+<h3><a name="Play">Intercepting Primitives</a></h3>
+
+ <p>To fill data structures of library primitives during a <font face="Courier New">cdPlay</font> call you must
+ implement a driver and activate it before calling <font face="Courier New">cdPlay</font>. Inside your driver
+ primitives you can fill your data structure with the information interpreted by the <font face="Courier New">cdPlay</font>
+ function.</p>
+
+<h3><a name="IUP">IUP Compatibility</a></h3>
+
+ <p>The <strong>IupCanvas</strong> element of the <a target="_blank" href="http://www.tecgraf.puc-rio.br/iup/">IUP</a>
+ interface toolkit can be used as a visualization surface for a CD canvas. There are two moments in which one must be
+ careful when an application is using both libraries: when creating the CD canvas, and when changing the size of the
+ IUP canvas.</p>
+ <h4>Creating the CD Canvas</h4>
+
+ <p>The CD_IUP driver parameter needs only the Ihandle* of the <strong>
+ IupCanvas</strong>. But <strong>cdCreateCanvas</strong> must be called <u>after</u> the <strong>IupCanvas</strong> element has been
+ mapped into the native system.</p>
+ <p>But a call to <strong>IupShow</strong> generates an ACTION callback. And a
+ direct call to <strong>IupMap</strong> can generate a RESIZE_CB callback.&nbsp; </p>
+ <p>So the best way to create a CD canvas for a IUP canvas is to use the
+ <strong>IupCanvas</strong> MAP_CB callback. This callback will be always called before
+ any other callback.</p>
+
+ <p>The application must be linked with the <strong>iupcd</strong>
+ library that it is available in the IUP package.</p>
+
+ <h4>Resizing the IUP Canvas</h4>
+
+ <p>When a IupCanvas is resized the CD canvas must be notified of the size
+ change. To do that simply call <strong>cdCanvasActivate</strong> in the
+ RESIZE_CB callback.</p>
+
+
+
+</body>
+
+</html>