1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
<!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;
}
.style1 {
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 "-lX11" 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 be 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 version for Posix systems is
already included in the source code package. Just type "make" in the command
line on the "src" folder and all libraries will be build. Set the TECTOOLS_HOME
environment variable to the folder were the IM and Lua libraries are installed,
by default it will assume "TECTOOLS_HOME=../..".</p>
<p>In Linux, check the "<a href="../../../iup/html/en/building.html">Building Lua, IM, CD and IUP in
Linux</a>" guide.</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 "src" folder are very easy to understand 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 9.0 (2008) for example, just execute <i>"make_uname vc9"</i> , or
for the
DLLs type <i>"make_uname dll9"</i>. The Visual
Studio workspaces with the respective projects available in the source package
is for debugging purposes only.</p>
<p>If you don't want to install Tecmake you can use the version for Windows
systems that is included in the source code package. BUt is is more complicated
that its Posix counterpart. First the GNU make must be installed and in the PATH
before other makes. In the command line you must specify the compiler path and
the TEC_UNAME variable. For example:</p>
<pre>make -f tecmakewin.mak TEC_UNAME=mingw4 MINGW4=c:/mingw
make -f tecmakewin.mak TEC_UNAME=gcc4 GCC4=c:/cygwin (Cygwin building for Win32)</pre>
<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 -> <strong><span class="style2">FreeType</span></strong> (included as separate library)
<em> cdwin*</em> -> <strong><span class="style4">gdi32</span></strong> <strong><span class="style4">user32</span></strong> <strong><span class="style4">comdlg32</span></strong> (system - Windows)
<em> cdx11*</em> -> <strong><span class="style4">X11</span></strong> (system - UNIX)
<em> </em><em>cdgdk+cdcairo*</em> -> <strong><span class="style1">gdk-win32-2.0 pangowin32-1.0</span></strong>(system - Windows)
<em> </em> -> <strong><span class="style1">gdk-x11-2.0</span></strong> <strong><span class="style1">pangox-1.0 </span></strong>(system - UNIX)
-> <span class="style1"><strong>cairo </strong></span><strong><span class="style1">gdk_pixbuf-2.0 pango-1.0 gobject-2.0</span></strong> <strong><span class="style1">gmodule-2.0 glib-2.0</span></strong> (system - Windows/UNIX)
<em>cdgdiplus*</em> -> cd
-> <strong><span class="style4">gdiplus</span></strong> (system - Windows)
<em>cdxrender*</em> -> cd
-> <strong><span class="style4">Xrender</span></strong> <strong><span class="style4">Xft</span></strong> (system - UNIX)
cdcairo -> <span class="style1"><strong>pangocairo-1.0 cairo</strong></span> (system - Windows/UNIX)
cdpdf -> <strong><span class="style2">pdflib</span></strong> (included as separate library)
<em>cd</em>gl -> <span class="style1">opengl32</span> (system - Windows)
-> <span class="style1">GL</span> (system - UNIX)
-> <strong><span class="style2">ftgl</span></strong> (included as separate library)
cdlua51 -> cd
-> <strong><span class="style3">lua5.1</span></strong>
cdluacontextplus -> cdlua51
-> cdcontextplus
cdluaim51 -> cdlua51
-> <strong><span class="style3">imlua51</span></strong>
cdluapdf51 -> cdlua51
-> cdpdf
cdluagl51 -> cdlua51
-> cdgl
(*) In Windows, "<strong>cdwin</strong>" is called "<strong>cd</strong>", "<strong>cdgdiplus</strong>" is called "<strong>cdcontextplus</strong>".
In Linux and BSD "<strong>cdgdk+cdcairo</strong>" is called "<strong>cd</strong>", "<strong>cdxrender</strong>" is called "<strong>cdcontextplus</strong>".
In IRIX, AIX and SunOS "<strong>cdx11</strong>" is called "<strong>cd</strong>", "<strong>cdxrender</strong>" is called "<strong>cdcontextplus</strong>".</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>
<p>The Lua bindings for IUP, CD and IM (Makefiles and Pre-compiled binaries)
depend on the <a href="http://luabinaries.luaforge.net/">LuaBinaries</a>
distribution. So if you are going to build all use the <strong>LuaBinaries</strong>
source package also, not the <strong>Lua.org</strong> original source package.
If you like to use another location for the Lua files define LUA_SUFFIX, LUA_INC,
LUA_LIB and LUA_BIN before using Tecmake or Tecmake Compact.</p>
<p>In Ubuntu you will need to install the following packages:</p>
<pre>libx11-dev
libxpm-dev
libxmu-dev
libxft-dev (for the XRender driver)
libgtk2.0-dev (for the GDK driver)</pre>
<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. </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>
|
