[pal-cvs] CVS pal/documentation
tneste
tneste at common-lisp.net
Wed Oct 31 12:51:23 UTC 2007
Update of /project/pal/cvsroot/pal/documentation
In directory clnet:/tmp/cvs-serv6234/documentation
Modified Files:
pal-manual.lyx pal-manual.pdf
Added Files:
pal-manual.tex
Log Message:
Some polishing. Version 1.1
--- /project/pal/cvsroot/pal/documentation/pal-manual.lyx 2007/10/18 19:29:56 1.2
+++ /project/pal/cvsroot/pal/documentation/pal-manual.lyx 2007/10/31 12:51:23 1.3
@@ -269,11 +269,11 @@
\end_layout
\begin_layout Subsection
-Introduction
+Resources
\end_layout
\begin_layout Subsection
-Functions
+Functions and macros
\end_layout
\begin_layout Description
@@ -447,7 +447,7 @@
\end_layout
\begin_layout Subsection
-Introduction
+Basics
\end_layout
\begin_layout Standard
@@ -464,7 +464,7 @@
\end_layout
\begin_layout Subsection
-Functions
+Functions and macros
\end_layout
\begin_layout Description
@@ -676,7 +676,7 @@
\shape italic
keysym
\shape default
-.
+, or NIL if the character is out the ASCII range 1-255.
\end_layout
@@ -1761,11 +1761,11 @@
\end_layout
\begin_layout Subsection
-SET-BLEND-MODE
+SET-BLEND
\end_layout
\begin_layout Subsection
-RESET-BLEND-MODE
+RESET-BLEND
\end_layout
\begin_layout Subsection
@@ -1971,10 +1971,6 @@
\end_layout
\begin_layout Subsection
-DATA-PATH
-\end_layout
-
-\begin_layout Subsection
RANDOMLY
\end_layout
@@ -1990,9 +1986,5 @@
DO-N
\end_layout
-\begin_layout Subsection
-CURRY
-\end_layout
-
\end_body
\end_document
Binary files /project/pal/cvsroot/pal/documentation/pal-manual.pdf 2007/10/18 19:29:56 1.1 and /project/pal/cvsroot/pal/documentation/pal-manual.pdf 2007/10/31 12:51:23 1.2 differ
--- /project/pal/cvsroot/pal/documentation/pal-manual.tex 2007/10/31 12:51:23 NONE
+++ /project/pal/cvsroot/pal/documentation/pal-manual.tex 2007/10/31 12:51:23 1.1
%% LyX 1.4.4 created this file. For more info, see http://www.lyx.org/.
%% Do not edit unless you really know what you are doing.
\documentclass[english]{article}
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\makeatletter
\usepackage{babel}
\makeatother
\begin{document}
\title{Pixel Art Library}
\author{Tomi Neste tneste at common-lisp.net}
\maketitle
\newpage{}
\begin{quote}
Pixel Art Library is published under the MIT license
Copyright (c) 2006 Tomi Neste
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the \char`\"{}Software\char`\"{}),
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:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED \char`\"{}AS IS\char`\"{}, 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{quote}
\newpage{}
\tableofcontents{}
\newpage{}
\section{Introduction and installation}
\subsection{What is Pixel Art Library}
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.
PAL's design goals are ease of use, portability and reliability. It
tries to provide all the \emph{common} 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.
\subsection{Requirements}
\begin{itemize}
\item 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{Note: These come with their
own license.}
\item 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.
\item For interfacing with the foreign libraries PAL uses the excellent
CFFI library. It's available from http://common-lisp.net/project/cffi
\item 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.
\item To get anywhere near reasonable performance you need a graphics card
and driver that is capable of hardware accelerated OpenGL graphics.
\end{itemize}
\subsection{Installation}
After installing CFFI (and possibly ASDF) and downloading and unpacking
PAL you should
\begin{itemize}
\item Under Windows copy the .dlls to somewhere where they can be found,
for example in your Lisp implementations home folder.
\item Under Linux, check that the SDL, SDL\_mixer and SDL\_image packages
are installed.
\item 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
\item 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.
\item If everything went fine you can now try your first PAL program, enter
in the following:
\end{itemize}
\begin{quotation}
\texttt{(with-pal (:title {}``PAL test'')}
\texttt{~~(clear-screen 255 255 0)}
\texttt{~~(with-transformation (:pos (v 400 300) :angle 45f0 :scale
4f0)}
\texttt{~~~~(draw-text {}``Hello World!'' (v 0 0))}
\texttt{~~~~(wait-keypress)))}
\end{quotation}
\newpage{}
\section{Opening and closing PAL and handling resources}
\subsection{Resources}
\subsection{Functions and macros}
\begin{description}
\item [{OPEN-PAL}] (\&key \textit{width height fps title fullscreenp paths})
\end{description}
Opens and initialises PAL window.
\begin{description}
\item [{\textit{width},}] width of the screen.
\item [{\textit{height},}] height of the screen. If width and height are
0 then the default desktop dimensions are used.
\item [{\textit{fps},}] maximum number of times per second that the screen
is updated.
\item [{\textit{title},}] title of the screen.
\item [{\textit{fullscreenp},}] open in windowed or fullscreen mode.
\item [{\textit{paths},}] pathname or list of pathnames that the load-{*}
functions use to find resources. Initially holds {*}default-pathname-defauls{*}
and PAL installation directory.
\item [{CLOSE-PAL}] ()
\end{description}
Closes PAL screen and frees all loaded resources.
\begin{description}
\item [{WITH-PAL}] (\&key \textit{width height fps title fullscreenp paths}
\&body \textit{body})
\end{description}
Opens PAL, executes \textit{body} and finally closes PAL. Arguments
are same as with OPEN-PAL.
\begin{description}
\item [{FREE-RESOURCE}] (\textit{resource})
\end{description}
Frees the \textit{resource} (image, font, sample or music).
\begin{description}
\item [{FREE-ALL-RESOURCES}] ()
\end{description}
Frees all allocated resources.
\begin{description}
\item [{WITH-RESOURCE}] (\textit{var init-form}) \&body \textit{body}
\end{description}
Binds \textit{var} to the result of \textit{init-form} and executes
\textit{body}. Finally calls FREE-RESOURCE on \textit{var.}
\begin{description}
\item [{GET-SCREEN-WIDTH}] () => \textit{number}
\item [{GET-SCREEN-HEIGHT}] () => \textit{number}
\end{description}
Returns the dimensions of PAL screen.
\newpage{}
\section{Event handling}
\subsection{Basics}
There are two ways to handle events in PAL; the callback based HANDLE-EVENTS
or EVENT-LOOP that call given functions when an event happens, or
directly polling for key and mouse state with TEST-KEYS, KEY-PRESSED-P
and GET-MOUSE-POS.
NOTE: Even if you don't need to use the callback approach it is still
necessary to call HANDLE-EVENTS on regular intervals, especially on
Windows. Running an EVENT-LOOP does this automatically for you and
is the preferred way to handle events.
\subsection{Functions and macros}
\begin{description}
\item [{HANDLE-EVENTS}] (\&key \textit{key-up-fn key-down-fn mouse-motion-fn
quit-fn})
\end{description}
Get next event, if any, and call appropriate handler function.
\begin{description}
\item [{\textit{key-up-fn},}] called with the released key-sym. For key-syms
see chapter 3.3
\item [{\textit{key-down-fn},}] called with the pressed key-sym. When \textit{key-down-fn}
is not defined pressing Esc-key causes a quit event.
\item [{\textit{mouse-motion-fn},}] called with x and y mouse coordinates.
\item [{\textit{quit-fn},}] called without any arguments when user presses
the windows close button. Also called when Esc key is pressed, unless
\textit{key-down-fn} is defined.
\item [{UPDATE-SCREEN}] ()
\end{description}
Updates the PAL screen. No output is visible until UPDATE-SCREEN is
called.
\begin{description}
\item [{EVENT-LOOP}] ((\&key \textit{key-up-fn key-down-fn mouse-motion-fn
quit-fn}) \&body \textit{body})
\end{description}
Repeatedly calls \textit{body} between HANDLE-EVENT and UPDATE-SCREEN.
Arguments are the same as with HANDLE-EVENTS. Returns when (return-from
event-loop) is called, or, if quit-fn is not given when quit event
is generated.
\begin{description}
\item [{GET-MOUSE-POS}] () => \textit{vector}
\item [{GET-MOUSE-X}] () => \textit{number}
\item [{GET-MOUSE-Y}] () => \textit{number}
\end{description}
Returns the current position of mouse pointer.
\begin{description}
\item [{SET-MOUSE-POS}] (\textit{vector})
\end{description}
Sets the position of mouse pointer.
\begin{description}
\item [{KEY-PRESSED-P}] (\textit{keysym}) => \textit{bool}
\end{description}
Test if the key \textit{keysym} is currently pressed down. For keysyms
see chapter 3.3
\begin{description}
\item [{TEST-KEYS}] ((\textit{key} | (\textit{keys}) \textit{form}))
\end{description}
Tests if any of the given keys are currently pressed. Evaluates \textit{all}
matching forms.
Example:
\begin{quotation}
(test-keys
~~(:key-left (move-left sprite))
~~(:key-right (move-right sprite))
~~((:key-ctrl :key-mouse-1) (shoot sprite))
\end{quotation}
\begin{description}
\item [{KEYSYM-CHAR}] (\textit{keysym}) => \textit{char}
\end{description}
Returns the corresponding Common Lisp character for \textit{keysym},
or NIL if the character is out the ASCII range 1-255.
\begin{description}
\item [{WAIT-KEYPRESS}] () => \textit{key}
\end{description}
Waits until a key is pressed and released
\subsection{Keysyms}
These are the symbols used to identify keyboard events. Note that
mouse button and scroll wheel events are also represented as keysyms.
\begin{quotation}
:key-mouse-1
:key-mouse-2
:key-mouse-3
:key-mouse-4
:key-mouse-5
:key-unknown
:key-first
:key-backspace
:key-tab
:key-clear
:key-return
:key-pause
:key-escape
:key-space
:key-exclaim
:key-quotedbl
:key-hash
:key-dollar
:key-ampersand
:key-quote
:key-leftparen
:key-rightparen
:key-asterisk
:key-plus
:key-comma
:key-minus
:key-period
:key-slash
:key-0
:key-1
:key-2
:key-3
:key-4
:key-5
:key-6
:key-7
:key-8
:key-9
:key-colon
:key-semicolon
:key-less
:key-equals
:key-greater
:key-question
:key-at
:key-leftbracket
:key-backslash
:key-rightbracket
:key-caret
:key-underscore
:key-backquote
:key-a
:key-b
:key-c
:key-d
:key-e
:key-f
[594 lines skipped]
More information about the Pal-cvs
mailing list