The CD library is a basic graphic library (GL). In a GL paradigm you use primitives, which have attributes, to draw on a canvas. All the library functions reflect this paradigm.
The canvas 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 driver. Only the driver knows how to draw on its surface. The user does not use the driver directly, but only the canvas.
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.
The attributes 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.
The set of primitives 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.
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 mechanism.
All the CD functions are declared in the cd.h header file; World Coordinate functions are declared in the wd.h 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 after the inclusion of the cd.h header file.
To link the application you must add the "cd" library. If statically linking then you will need at least the "freetype" and the "zlib" libraries. If you use an IUP Canvas then you must also link with the "iupcd" library available in the IUP distribution. Other drivers may need additional secondary libraries.
In UNIX, CD uses GDK or the Xlib (X11) libraries. To statically link an application in UNIX with CD, add also the GDK or the X11 libraries.
The download files list includes the Tecgraf/PUC-Rio Library Download Tips document, with a description of all the available binaries.
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 http://www.tecgraf.puc-rio.br/tecmake. Tecmake is used by all the Tecgraf libraries and many applications.
You do not need to install Tecmake, scripts for Posix and Windows systems are already included in the source code package. Just type "make" in the command line on the main folder and all libraries and executables will be build.
In Linux, check the "Building Lua, IM, CD and IUP in Linux" guide.
In Windows, check the "Building Lua, IM, CD and IUP in Window" guide.
If you decide to install Tecmake, the Tecmake configuration files (*.mak) are available at the "src" folder, and are very easy to understand. In the main folder, and in each source folder, there are files named make_uname.bat that build the libraries using Tecmake. To build for Windows using Visual C 9.0 (2008) for example, just execute "make_uname vc9" in the iup main folder, or for the DLLs type "make_uname dll9". The Visual Studio workspaces with the respective projects available in the source package is for debugging purposes only.
Make sure you have all the dependencies for the library you want installed, see the documentation bellow.
If you are going to build all the libraries, the makefiles and projects expect the following directory tree:
\mylibs\
cd\
im\
lua5.1\
To control that location set the TECTOOLS_HOME environment variable to the folder were the IM and Lua libraries are installed.
cd -> FreeType -> zlib (included as separate libraries) cdwin* -> gdi32 user32 comdlg32 (system - Windows) cdx11* -> X11 (system - UNIX) -> fontconfig (system - Linux) cdgdk+cdcairo* -> gdk-win32-2.0/gdk-3 pangowin32-1.0(system - Windows) -> gdk-x11-2.0/gdk-3 pangox-1.0 (system - UNIX) -> cairo gdk_pixbuf-2.0 pango-1.0 gobject-2.0 gmodule-2.0 glib-2.0 (system - Windows/UNIX) cdgdiplus* -> cd -> gdiplus (system - Windows) cdxrender* -> cd -> Xrender Xft (system - UNIX) cdcairo -> pangocairo-1.0 cairo (system - Windows/UNIX) cdpdf -> pdflib -> zlib (included as separate libraries) cdgl -> opengl32 (system - Windows) -> GL (system - UNIX) -> ftgl (included as separate library) cdlua51 -> cd -> lua5.1 cdluacontextplus -> cdlua51 -> cdcontextplus cdluaim51 -> cdlua51 -> imlua51 cdluapdf51 -> cdlua51 -> cdpdf cdluagl51 -> cdlua51 -> cdgl (*) In Windows, "cdwin" is called "cd", "cdgdiplus" is called "cdcontextplus". In Linux and BSD "cdgdk+cdcairo" is called "cd", "cdxrender" is called "cdcontextplus". In IRIX, AIX and SunOS "cdx11" is called "cd", "cdxrender" is called "cdcontextplus".
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.
The Lua bindings for IUP, CD and IM (Makefiles and Pre-compiled binaries) depend on the LuaBinaries distribution. So if you are going to build from source, then use the LuaBinaries source package also, not the Lua.org 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.
To build the driver with GTK 3.x support define USE_GTK3=Yes before calling make in the "cd/src" folder. Just the main library must be rebuilt.
In Ubuntu you will need to install the following packages:
libfreetype6-dev
libgl1-mesa-dev and libglu1-mesa-dev (for the ftgl library used by CD_GL)
libgtk2.0-dev (for the GDK driver)
or
libgtk3.0-dev (for the GTK driver)
libx11-dev (for the X11 driver, OPTIONAL)
libxpm-dev (")
libxmu-dev (")
libxft-dev (for the XRender driver, OPTIONAL)
CDDIR - 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.
CD_QUIET - In UNIX, if this variable is defined, it does not show the library's
version info on sdtout.
CD_XERROR - In UNIX, if this variable is
defined, it will show the X-Windows error messages on sdterr.
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 CDXX.H and CDXX.C. But first you should read the Internal Architecture.
To fill data structures of library primitives during a cdPlay call you must implement a driver and activate it before calling cdPlay. Inside your driver primitives you can fill your data structure with the information interpreted by the cdPlay function.
The IupCanvas element of the IUP 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.
The CD_IUP driver parameter needs only the Ihandle* of the IupCanvas. But cdCreateCanvas must be called after the IupCanvas element has been mapped into the native system.
But a call to IupShow generates an ACTION callback. And a direct call to IupMap can generate a RESIZE_CB callback.
So the best way to create a CD canvas for a IUP canvas is to use the IupCanvas MAP_CB callback. This callback will be always called before any other callback.
The application must be linked with the iupcd library that it is available in the IUP package.
When a IupCanvas is resized the CD canvas must be notified of the size change. To do that simply call cdCanvasActivate in the RESIZE_CB callback.