Main Page   Class Hierarchy   Compound List   File List   Compound Members   File Members

Razor.doxy.mainpage

Go to the documentation of this file.
00001 /**
00002 @mainpage Razor! Engine Developer's Guide
00003  
00004 @section intro Introduction
00005 Razor! is a highly modular, easy to use, embeddable presentation engine for Palm Powered(tm) devices. 
00006 It makes it easier for developers to create multimedia software, such as animations and games.
00007 The engine is not a ready-to-use executable. Instead it comes as a bundle of C++ source files which need to
00008 be customized, compiled and linked with your own code.
00009 <p>
00010 Its main features include
00011 <ul>
00012 <li><em>Timing + Flow control</em> - Razor! ensures the correct order of all actions, and their precise timing.</li>
00013 <li><em>%Canvas management</em> - Razor! manages the drawing area (aka %Canvas). It provides double buffering with optimized copying.</li>
00014 <li><em>%Sprite engine</em> - Razor! can draw sprites (small bitmaps with transparent parts). It manages their position, shown/hidden state, etc.</li>
00015 <li><em>Sound engine</em> - Razor! can play music (faking three voices), and sound FX.</li>
00016 <li><em>Input management</em> - Razor! can poll the hard keys, and direct other events to your app.</li>
00017 </ul>
00018 </p>
00019 @section license Licensing Terms
00020 Razor! is being licensed to you under the GNU LGPL license. Read the file <code>COPYING.TXT</code> that is included with this distribution
00021 to find out your rights in using this library. Essentially, there is <em>NO WARRANTY</em>, and you may merge this library with your own
00022 code whether it is commercial, or not, provided that you make improvements to the Razor! Engine (but not the code of your application)
00023 publically available in source code form.
00024 
00025 
00026 @section contents Contents
00027 Section @ref getting_started_page contains information about requirements and installation
00028 <br>
00029 Section @ref framework_page contains an overview over the framework
00030 <br>
00031 Section @ref credits_page contains thanks to all contributors
00032 */
00033 
00034 /**
00035 @page getting_started_page Getting Started
00036 @subsection requirements Requirements
00037 <b>Palm Powered(tm) device</b><br>
00038 Any device running Palm OS 3.0, or higher
00039 <p>
00040 <b>Development environment</b><br>
00041 <ul>
00042 <li>Metrowerks CodeWarrior R6 (or CodeWarrior Lite) with Palm OS SDK 3.5 and Update 1</li>
00043 <li>Optional: PilRC 2.5c and the PilRC plug-in for Codewarrior (from: <a href="http://www.ardiri.com">http://www.ardiri.com</a>)</li>
00044 </ul>
00045 or
00046 <ul>
00047 <li>PRC-Tools 2.0 with Palm OS SDK 3.5</li>
00048 <li>PilRC 2.5c (from: <a href="http://www.ardiri.com">http://www.ardiri.com</a>)</li>
00049 <li>Optional: Falch.net DeveloperStudio 2.0 (from: <a href="http://www.falch.net">http://www.falch.net</a>)</li>
00050 </ul>
00051 @subsection installation Installation
00052 Make sure your development environment is properly installed. Download the Razor! distribution archive and unpack it into an
00053 arbitrary directory. Use the supplied project file (<code>Razor.mcp</code> for CodeWarrior, <code>Razor.FNP</code> for Falch.net, 
00054 <code>Makefile</code> for bare-bones PRC-Tools) in order to build a functional PRC-file. Run the PRC file on a Palm Powered(tm) 
00055 device, or on the POSE emulator. If there are no errors, then you are all set.
00056 */
00057 
00058 /**
00059 @page framework_page The Framework
00060 @subsection overview Overview
00061 Razor! is a highly modular, easy to use, embeddable presentation engine for Palm Powered(tm) devices. 
00062 It makes it easier for developers to create multimedia software, such as animations and games.
00063 Razor! is written in C++ and is delivered as a so-called <em>hybrid framework</em>.
00064 @subsection framework Framework vs. Class Library
00065 It is important to understand the nature of a framework, especially in comparison to a class library.
00066 Frameworks operate by the &quot;Hollywood principle&quot; (don't call us, we'll call you). That means,
00067 the framework controls the entire flow of your application's execution, calling your code in a few well-defined
00068 places. When you are using a class library, it is just the other way around: You control the flow, and make
00069 calls into the library.
00070 <br>
00071 A framework is harder to design than a class library, but provided that your application fits the domain of
00072 the framework, it can save you a lot of work, and provide results of superior quality, because you are not
00073 only using proven code, but also proven patterns for application design.
00074 <br>
00075 In reality, you will rarely find a pure framework. Most frameworks are also accompanied by a class library. These
00076 are called <em>hybrid frameworks</em>.
00077 @subsection hotspots Hotspots
00078 The places in your code, which are invoked by the framework, are called <em>hotspots</em>. These are the places where
00079 you are given the chance to customize the behavior of the resulting application. Razor! bundles all hotspots in one place:
00080 There is a class called ActionEngine which contains several pure virtual operations, which shall be overridden by you.
00081 @subsection customization Customizing Razor!
00082 As mentioned before, Razor! bundles all hotspots in the ActionEngine class. In order to customize Razor!, you will need to
00083 create a specialization of ActionEngine (using inheritance), and you will need to change the file &quot;ActionEngineFactory.h&quot;
00084 in order to tell Razor! the name of your new class. Look at the class DemoActionEngine for a working example of an
00085 ActionEngine. Some further customizations can be made through modifications of the file &quot;Customization.h&quot;
00086 */
00087  
00088 /**
00089 @page credits_page Credits
00090 @subsection thanks I wish to thank the following people
00091 <ul>
00092 <li>Dimitri van Heesch (dimitri@stack.nl) for the <a href="http://www.stack.nl/~dimitri/doxygen/index.html">doxygen</a> documentation tool</li>
00093 <li>Aaron Ardiri (aaron@ardiri.com) and Wes Cherry (wesc@technosis.com) for the <a href="http://www.ardiri.com">PilRC resource compiler</a></li>
00094 <li>Neil Rhodes (neil@pobox.com) for the <a href="http://www.calliopeinc.com/devcorner.htm">Codewarrior PilRC plugin</a></li>
00095 </ul>
00096 */
00097 

Razor! Engine Developer's Guide. Copyright © by Tilo Christ. All Rights Reserved. Last updated: 4 Nov 2000