<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Creating Applications using lispbuilder-openrm (CFFI bindings for OpenRM)</title>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=iso-8859-1" />
<style type="text/css">
body {
margin: 10px 20px 20px 200px;
padding: 0px;
font-family: Verdana, Geneva, Arial, Helvetica, sans-serif;
font-size: small;
text-align: justify;
max-width: 50em;
background-color: white;
}
a, a:visited {
text-decoration: none;
color: maroon;
}
/* index */
div.index {
position: fixed;
top: 0px;
left: 0px;
width: 160px;
height: 100%;
margin: 0px;
padding: 5px;
font-size: 12px;
background-color: #DCDCDC;
border-right: thin black solid;
}
div.index ol {
color: navy;
margin: 0px;
padding-left: 0px;
}
div.index ol li {
list-style: none;
}
div.index ol li:before {
display: marker;
content: counter(heading1) ". ";
counter-increment: heading1;
}
div.index ol ol {
padding-left: 10px;
font-size: 10px;
list-style: none;
counter-reset: heading2;
}
div.index ol ol li:before {
display: marker;
content: counter(heading1)"." counter(heading2)" ";
counter-increment: heading2;
}
/* heading styles */
body > h1 {
margin-top: 0px;
}
h1 {
margin-top: 40px;
margin-bottom: 0px;
color: #4682B4;
}
h1:before {
display: marker;
content: counter(chapter) ". ";
counter-increment: chapter;
counter-reset: section1;
}
h1 + p {
margin-top: 5px;
}
h2 {
margin-top: 20px;
color: #000000;
margin-bottom: 0px;
}
h2:before {
display: marker;
content: counter(chapter) "." counter(section1) " ";
counter-increment: section1;
}
h2 + p {
margin-top: 0px;
}
h3 {
margin-top: 20px;
color: #000000;
margin-bottom: 0px;
}
h3:before {
display: marker;
content: counter(chapter) "." counter(section1) "." counter(section2) " ";
counter-increment: section2;
}
h3 + p {
margin-top: 0px;
}
h4 {
margin-top: 20px;
color: #000000;
margin-bottom: 0px;
}
h4:before {
display: marker;
content: counter(chapter) "." counter(section1) "." counter(section2) "." counter(section3) " ";
counter-increment: section3;
}
h4 + p {
margin-top: 0px;
}
/* generated content for images and tables */
img:after {
content: "[" counter(image) "] " attr(title);
counter-increment: image;
display: block;
font-size: 10px;
font-weight: bold;
margin-top: 5px;
margin-bottom: 20px;
color: black;
}
table:after {
content: "Table " counter(table) ": " attr(summary);
counter-increment: table;
display: table-caption;
caption-side: bottom;
font-size: 10px;
font-weight: bold;
margin-top: 5px;
margin-bottom: 20px;
white-space: nowrap;
color: black;
}
/* code for examples, code and pathnames*/
div.example table {
color: black;
}
div.example, div.code, div.path, div.sequence {
margin: 10px 0px;
border: 1px black solid;
padding: 10px;
background-color: #F4F4F4;
counter-reset: image;
color: maroon;
}
div.example:before {
content: "Example " counter(example);
counter-increment: example;
display: block;
}
div.example + p {
margin-bottom: 0px;
}
div.code:before {
content: "Code";
}
div.path:before {
content: "Path";
}
div.sequence:before {
content: "Sequence";
}
p.reference:before {
display: marker;
content: "[" counter(reference) "]";
counter-increment: reference;
font-weight: bold;
margin-right: 5px;
}
div.code:before, div.example:before, div.path:before, div.sequence:before {
font-weight: bold;
font-size: 15px;
margin-bottom: 20px;
color: black;
}
pre {
color: Green;
margin: 0px;
padding: 0px;
}
/* equation counter */
e:after {
content: "[" counter(equation) "]";
counter-increment: equation;
display: block;
float: right;
margin-right: 10px;
}
/* to prevent the CC image from being numbered */
img[alt="Creative Commons License"] {
display: inline;
}
img[alt="Creative Commons License"]:after {
display: none;
}
div#cc {
background-color: #DCDCDC;
border: thin black solid;
padding: 10px;
font-size: 10px;
}
</style>
</head>
<!--
(CC) 2006 Luke Crook. Some Rights Reserved.
http://creativecommons.org/licenses/by/1.0
This page is licensed under a Creative Commons License.
Maintained by the Common Lisp Application Builder project at www.lispbuilder.org
The entire styleguide was copied wholesale from http://www.markschenk.com/cssexp/publication/article.xml
(CC) 2003 Mark Schenk. Some Rights Reserved.
http://creativecommons.org/licenses/by/1.0
This page is licensed under a Creative Commons License.
-->
<BODY BGCOLOR=#FFFFFF >
<h1 id="lispbuilder-openrm">lispbuilder-openrm</h1>
<h2 id="Overview">Overview</h2>
<p>The <a href="http://www.openrm.org/">OpenRM Scene Graph</a> implements a scene graph API using OpenGL for
hardware accelerated rendering. OpenRM is intended to be used to construct high performance, portable graphics and
scientific visualization applications on Unix/Linux/Windows platforms.</p>
<p>lispbuilder-openrm provides the bindings and utility functions necessary to integrate OpenRM with Common Lisp.</p>
<p>The lispbuilder-openrm relies on the OpenGL libraries being installed on the host OS. Although lispbuilder-openrm
itself does not require <a href="../../lispbuilder-sdl/documentation/index.html">lispbuilder-sdl</a>,
several of the OpenRM examples require SDL to manage the window, key handling and creation of the OpenGL context.
OpenRM itself provides support for this, but this has not yet been tested in these bindings.
<p>The lispbuilder-openrm package is a part of the
<a href="http://www.lispbuilder.org/">Common Lisp Application Builder</a> project which is in turn a part of the
umbrella <a href="http://www.lispniks.com/cl-gardeners/">Common Lisp Gardeners</a> project.</p>
<p>The purpose of this document is to describe a step-by-step process by which the user may install, configure and
begin using the lispbuilder-openrm package to create applications using one of the
<a href="#Implementations">supported Lisp implementations</a>.</p>
<p>The list of credits is contained in <a href="../documentation/CONTRIBUTORS">CONTRIBUTORS</a>. A copy of the license is contained in
<a href="../documentation/COPYING">COPYING</a>.</p>
<h2 id="Implementations">Supported Implementations</h2>
<p>The following table describes the status of the Lisp implementations that have been tested with lispbuilder-openrm:</p>
<table border="1" cellpadding="2" cellspacing="0" summary="Supported Implementations">
<tr bgcolor="yellow">
<td><b>Lisp Implementation</b></td>
<td colspan="3"><b>lispbuilder-openrm Status</b></td>
<td><b>Comments</b></td>
</tr>
<tr bgcolor="yellow">
<td colspan="1"></td>
<td><b>Win32</b></td>
<td><b>Linux</b></td>
<td><b>MacOS</b></td>
<td></td></td>
</tr>
<tr>
<td><a href="http://clisp.cons.org/">CLISP v2.38</a></td>
<td bgcolor="#60c060">Working</td>
<td bgcolor="#ff6060">Unknown</td>
<td bgcolor="#ff6060">Unknown</td>
<td></td>
</tr>
<tr>
<td><a href="http://www.lispworks.com/">Lispworks v2.4.6 Personal</a></td>
<td bgcolor="#60c060">Working</td>
<td bgcolor="#ff6060">Unknown</td>
<td bgcolor="#ff6060">Unknown</td>
<td>As of [03/30/06], use the 'CFFI-060214' tarball for Windows as more recent versions do not work.</td>
</tr>
<tr>
<td><a href="http://www.franz.com/">Allegro Trial Edition 7.0</a></td>
<td bgcolor="#ff6060">Unknown</td>
<td bgcolor="#ff6060">Unknown</td>
<td bgcolor="#ff6060">Unknown</td>
<td></td>
</tr>
<tr>
<td><a href="http://openmcl.clozure.com/">OpenMCL</a></td>
<td bgcolor=blue><font color="#FFFFFF">NA</font></td>
<td bgcolor=blue><font color="#FFFFFF">NA</font></td>
<td bgcolor="#ff6060">Unknown</td>
<td></td>
</tr>
<tr>
<td><a href="http://www.sbcl.org/">SBCL</a></td>
<td bgcolor=blue><font color="#FFFFFF">When, oh when?</font></td>
<td bgcolor="#60c060">Working</td>
<td bgcolor="#ff6060">Unknown</td>
<td>
</td>
</tr>
<tr>
<td><a href="http://www.cons.org/cmucl/">CMUCL</a></td>
<td bgcolor=blue><font color="#FFFFFF">When already?</font></td>
<td bgcolor="#ff6060">Unknown</td>
<td bgcolor=blue><font color="#FFFFFF">NA</font></td>
<td>
Justin WIP Debian (sarge)
</td>
</tr>
</table>
<h2 id="Prerequisites">Prerequisites</h2>
<p>The packages
<u><a href="http://cvs.sourceforge.net/viewcvs.py/*checkout*/cclan/asdf/asdf.lisp?rev=1.92">asdf.lisp</a></u>,
<u><a href="http://common-lisp.net/project/cffi/tarballs/cffi-060225.tar.gz">CFFI</a></u> and
<u><a href="../../lispbuilder-sdl/documentation/index.html">lispbuilder-sdl</a></u>
must be installed prior to the installation of lispbuilder-openrm. The installation procedures for these pacakges are
described in the <a href="../../lispbuilder-sdl/documentation/index.html">lispbuilder-sdl documentation</a></u>.</p>
<p>In addition the the lisp packages described above, OpenRM for Windows requires the
<u><a href="http://sourceware.org/pthreads-win32/">PThreads Win32</a></u> libraries, as well as the Windows specific
<u>msvcr70.dll</u> and <u>msvcrtd.dll</u> libraries. All these binaries are included in the
<a href="http://sourceforge.net/project/showfiles.php?group_id=159740&package_id=182505">lispbuilder-openrm-binaries</a>
package on sourceforge. The installation instructions for this package are described <a href="#Win32: lispbuilder-openrm and the OpenRM binaries">below</a>. The Linux installation does not require these additional binaries.</p>
<h2 id="Win32: lispbuilder-openrm">Installation on Win32 Platforms</h2>
<h3 id="Win32: lispbuilder-openrm">Installation of lispbuilder-openrm</h3>
<p>This section describes the installation of the lispbuilder-openrm package.</p>
<ul>
<li> download the latest version of the
<a href="http://sourceforge.net/project/showfiles.php?group_id=159740">lispbuilder-openrm</a>
package from sourceforge and unpack it to the asdf directory, e.g.
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm_0.1\lispbuilder-openrm.asd</pre>
</li>
</ul>
<h3 id="Win32: lispbuilder-openrm and the OpenRM binaries">Installation of the OpenRM binaries</h3>
<p>This section describes the installation of the OpenRM binaries for Windows.</p>
<ul>
<li>Install the OpenRM libraries by performing the following:
<ul>
<li>Download the <a href="http://sourceforge.net/project/showfiles.php?group_id=159740&package_id=182505">lispbuilder-openrm-binaries</a> package from sourceforge and unpack it into the asdf directory, e.g.
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\lispbuilder-openrm-binaries.asd</pre>
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\bin\librm.dll</pre>
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\bin\librmaux.dll</pre>
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\bin\librmi.dll</pre>
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\bin\librmv.dll</pre>
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\bin\msvcr70.dll</pre>
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\bin\msvcrtd.dll</pre>
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\bin\pthreadGC.dll</pre>
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\bin\pthreadGCE.dll</pre>
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\bin\pthreadVC.dll</pre>
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\bin\pthreadVCE.dll</pre>
<pre>c:\programme\clisp-2.38\asdf\lispbuilder-openrm\bin\pthreadVSE.dll</pre>
</li>
</ul>
</ul>
<h2 id="Installation">Installation on Linux Platforms</h2>
<h3 id="Linux: lispbuilder-openrm">Installation of lispbuilder-openrm</h3>
<p>This section describes the installation of the lispbuilder-openrm package for Linux users. Download the latest version
of the <a href="http://sourceforge.net/project/showfiles.php?group_id=159740">lispbuilder-openrm</a>
package from sourceforge, and:</p>
<ul>
<li><u>ASDF-Install</u>: The package is ASDF-Install'able, so install the package using ASDF-install: <code>(asdf-install:install "lispbuilder-openrm_0.1.tgz")</code>, or</li>
<li><u>Manual installation</u>: Extract the package to the correct asdf systems directory.
</li>
</ul>
<h3 id="Linux: The OpenRM binary">Installation of the OpenRM binaries</h3>
<p>This section describes the installation of the OpenRM binaries for Linux.</p>
<ul>
<li>For Fedora Linux:
<ul>
<li><u>Manual Installation</u>: Download and install the OpenRM RPMs from the <a href="http://www.openrm.org/">official OpenRM site</a>
</li>
</ul>
</ul>
<h2>Configuration on Win32 Platforms</h2>
<h3>ASDF Configuration</h3>
<div class="code">
<p>Add the following to the ASDF *central-registry*:</p>
<pre>
(pushnew "/programme/clisp-2.38/asdf/lispbuilder-openrm_0.1/" asdf:*central-registry*)
</pre>
<p>Set "lispbuilder-openrm_0.1/" to the version number of the lispbuilder-openrm package, e.g. "lispbuilder-openrm_{version_number}/".
</div>
<h2 id="Fire it Up">Fire it Up</h2>
<div class="sequence">
<p>Now start CLISP and enter the following at the prompt:</p>
<pre>
(load "c:/programme/clisp-2.38/asdf/asdf.lisp")
(asdf:operate 'asdf:load-op :lispbuilder-openrm-examples)
</pre>
<p>ASDF will take care of loading the CFFI, :lispbuilder-sdl and :lispbuilder-openrm dependencies.
The OpenRM binaries will also be loaded into the Lisp image at this time.</p>
<p>Great. If you received any errors during this processes then go back and verify that the pathnames entered into the
*central-registry* match the directories where the packages were installed. Also verify that the OpenRM binaries are
located somewhere in the search path, as described above.</p>
</div>
<h2 id="Running the included OpenRM examples">Running the included OpenRM examples</h2>
<div class="example">
<p>To verify that lispbuilder-openrm is installed correctly, run the example by entering:</p>
<pre>
(rm-examples:jballs)
</pre>
<p>You should see a window as show below. Click-drag the mouse using the left, right or middle mouse buttons to
arc, dolly and translate the camera viewpoint.</p>
<img src="openrm1.jpg" width="320" height="253" title="(rm-examples:jballs)" alt="jballs" />
<p>The 'A' key will display bounding boxes around each object in the scene:</p>
<img src="openrm2.jpg" width="320" height="202" title="(rm-examples:jballs)" alt="jballs bounding boxes" />
</div>
<div class="example">
<pre>
(rm-examples:spotlight)
</pre>
<p>Click-drag the mouse while depressing the left mouse button to rotate the spotlight.</p>
<img src="openrm3.jpg" width="320" height="266" title="(rm-examples:spotlight)" alt="spotlight" />
</div>
</body>
</html>
