[pal-cvs] CVS pal/documentation

tneste tneste at common-lisp.net
Thu Oct 18 16:41:02 UTC 2007 

Update of /project/pal/cvsroot/pal/documentation
In directory clnet:/tmp/cvs-serv18242/documentation

Added Files:
	pal-manual.lyx 
Log Message:
Added the manual. Removed few unnecessarily exported functions.


--- /project/pal/cvsroot/pal/documentation/pal-manual.lyx	2007/10/18 16:41:02	NONE
+++ /project/pal/cvsroot/pal/documentation/pal-manual.lyx	2007/10/18 16:41:02	1.1
#LyX 1.4.4 created this file. For more info see http://www.lyx.org/
\lyxformat 245
\begin_document
\begin_header
\textclass article
\language english
\inputencoding auto
\fontscheme default
\graphics default
\paperfontsize default
\papersize default
\use_geometry false
\use_amsmath 1
\cite_engine basic
\use_bibtopic false
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\papercolumns 1
\papersides 1
\paperpagestyle default
\tracking_changes false
\output_changes false
\end_header

\begin_body

\begin_layout Title
Pixel Art Library
\end_layout

\begin_layout Author
Tomi Neste tneste at common-lisp.net
\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Quote
Pixel Art Library is published under the MIT license
\end_layout

\begin_layout Quote
Copyright (c) 2006 Tomi Neste
\end_layout

\begin_layout Quote
Permission is hereby granted, free of charge, to any person obtaining a
 copy of this software and associated documentation files (the "Software"),
 to deal in the Software without restriction, including without limitation
 the rights to use, copy, modify, merge, publish, distribute, sublicense,
 and/or sell copies of the Software, and to permit persons to whom the Software
 is furnished to do so, subject to the following conditions:
\end_layout

\begin_layout Quote
The above copyright notice and this permission notice shall be included
 in all copies or substantial portions of the Software.
 
\end_layout

\begin_layout Quote
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
 DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE
, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 OTHER DEALINGS IN THE SOFTWARE.
 
\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Standard
\begin_inset LatexCommand \tableofcontents{}

\end_inset


\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Section
Introduction and installation
\end_layout

\begin_layout Subsection
What is Pixel Art Library
\end_layout

\begin_layout Standard
PAL is a Common Lisp library for developing applications with fast 2d graphics
 and sound.
 Internally it uses SDL for sound, event handling and window initialisation
 and OpenGL for fast hardware accelerated graphics but its API has little
 to do with the aforementioned libraries.
\end_layout

\begin_layout Standard
PAL's design goals are ease of use, portability and reliability.
 It tries to provide all the 
\emph on
common
\emph default
 functionality that is needed when creating 2d games and similar applications.
 As such it neither provides higher level specialised facilities like sprites
 or collision detection, or lower level OpenGL specific functionality.
 If the user is familiar with Common Lisp and OpenGL this kind of functionality
 should be easy to implement on top of PAL.
\end_layout

\begin_layout Subsection
Requirements
\end_layout

\begin_layout Itemize
Pixel Art Library requires the SDL, SDL_image and SDL_mixer libraries.
 For Windows users it's easiest to use the ones included in the PAL releases,
 Linux users should be able to easily install these through their distros
 package management.
 
\emph on
Note: These come with their own license.
\end_layout

\begin_layout Itemize
Like most modern CL libraries PAL uses ASDF to handle compilation and loading.
 If you are using SBCL this is included with the default installation and
 can be loaded with (REQUIRE :ASDF), with other systems you may need to
 download it separately.
\end_layout

\begin_layout Itemize
For interfacing with the foreign libraries PAL uses the excellent CFFI library.
 It's available from http://common-lisp.net/project/cffi
\end_layout

\begin_layout Itemize
For creating the bitmap fonts that PAL uses you need the font creator that
 is included in Haaf's Game Engine.
 This will be fixed in the future releases.
\end_layout

\begin_layout Itemize
To get anywhere near reasonable performance you need a graphics card and
 driver that is capable of hardware accelerated OpenGL graphics.
\end_layout

\begin_layout Subsection
Installation
\end_layout

\begin_layout Standard
After installing CFFI (and possibly ASDF) and downloading and unpacking
 PAL you should
\end_layout

\begin_layout Itemize
Under Windows copy the .dlls to somewhere where they can be found, for example
 in your Lisp implementations home folder.
\end_layout

\begin_layout Itemize
Under Linux, check that the SDL, SDL_mixer and SDL_image packages are installed.
\end_layout

\begin_layout Itemize
Copy the PAL folder to where you usually keep your ASDF systems.
 If you are unsure you can check and modify this through ASDF:*CENTRAL-REGISTRY*
 variable
\end_layout

\begin_layout Itemize
In your Lisp prompt do (ASDF:OOS 'ASDF:LOAD-OP :PAL) and after awhile everything
 should be compiled and loaded in your Lisp session.
 In case of errors first check that everything, including the foreign libraries
 can be found by the system.
 If nothing works feel free to bug the Pal-dev mailing list.
 
\end_layout

\begin_layout Itemize
If everything went fine you can now try your first PAL program, enter in
 the following:
\end_layout

\begin_layout Quotation

\family typewriter
(with-pal (:title 
\begin_inset Quotes eld
\end_inset

PAL test
\begin_inset Quotes erd
\end_inset

)
\end_layout

\begin_layout Quotation

\family typewriter
\InsetSpace ~
\InsetSpace ~
(clear-screen 255 255 0)
\end_layout

\begin_layout Quotation

\family typewriter
\InsetSpace ~
\InsetSpace ~
(with-transformation (:pos (v 400 300) :angle 45f0 :scale 4f0)
\end_layout

\begin_layout Quotation

\family typewriter
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
(draw-text 
\begin_inset Quotes eld
\end_inset

Hello World!
\begin_inset Quotes erd
\end_inset

 (v 0 0))
\end_layout

\begin_layout Quotation

\family typewriter
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
\InsetSpace ~
(wait-keypress)))
\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Section
Opening and closing PAL and handling resources
\end_layout

\begin_layout Subsection
OPEN-PAL
\end_layout

\begin_layout Subsection
CLOSE-PAL
\end_layout

\begin_layout Subsection
WITH-PAL
\end_layout

\begin_layout Subsection
LOAD-FOREIGN-LIBRARIES
\end_layout

\begin_layout Subsection
FREE-RESOURCE
\end_layout

\begin_layout Subsection
FREE-ALL-RESOURCES
\end_layout

\begin_layout Subsection
WITH-RESOURCE
\end_layout

\begin_layout Subsection
GET-SCREEN-WIDTH, GET-SCREEN-HEIGHT
\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Section
Event handling
\end_layout

\begin_layout Subsection
HANDLE-EVENTS
\end_layout

\begin_layout Subsection
EVENT-LOOP
\end_layout

\begin_layout Subsection
GET-MOUSE-POS, GET-MOUSE-X, GET-MOUSE-Y
\end_layout

\begin_layout Subsection
KEY-PRESSED-P
\end_layout

\begin_layout Subsection
TEST-KEYS
\end_layout

\begin_layout Subsection
KEYSYM-CHAR
\end_layout

\begin_layout Subsection
WAIT-KEYPRESS
\end_layout

\begin_layout Subsection
UPDATE-SCREEN
\end_layout

\begin_layout Standard

\newpage

\end_layout

\begin_layout Section
Images and drawing
\end_layout

\begin_layout Subsection
CLEAR-SCREEN
\end_layout

\begin_layout Subsection
DRAW-POINT
\end_layout

\begin_layout Subsection
DRAW-LINE
\end_layout

\begin_layout Subsection
DRAW-ARROW
\end_layout

\begin_layout Subsection
LOAD-IMAGE
\end_layout

\begin_layout Subsection
IMAGE-WIDTH, IMAGE-HEIGHT
\end_layout

\begin_layout Subsection
DRAW-IMAGE
\end_layout

\begin_layout Subsection
DRAW-IMAGE*
\end_layout

\begin_layout Subsection
DRAW-RECTANGLE
\end_layout

\begin_layout Subsection
DRAW-CIRCLE
\end_layout

\begin_layout Subsection
DRAW-POLYGON
\end_layout

\begin_layout Subsection
DRAW-POLYGON*

[288 lines skipped]

More information about the Pal-cvs mailing list