S60 Platform: 3D Game Engine Example with Sensor Support v1.2
-------------------------------------------------------------

This C++ example application demonstrates a simple 3D engine. The engine
produces a simple car game where you can drive a car around a wide parking lot.
Everything seen on the screen is rendered in 3D. The example utilizes OpenGL
ES and the application dynamically scales on all screen sizes of S60 devices. 

The updated version introduces sensor support to the application. On devices that support the accelerometer 
Sensor, you can control the steering and throttle simply by moving the device. The 
example application provides support for both sensor and keypad.



PREREQUISITES
-------------------------------------------------------------------------------

Symbian C++ basics
Basics of 3D graphics
    All the techniques used in 3D are commonly known math and 3D graphics
    techniques. More information about the techniques used in the example can
    be found from the Internet with, for example, the following keywords:
    "3D clipping"
    "frustum clipping"
    "3D rotating matrices"
    "3D vertex projection"
    "painter's algorithm"
    "texture mapped polygons"
    "fast affine mapping"


IMPORTANT FILES/CLASSES
-------------------------------------------------------------------------------

The C3DRenderer takes care of rotating the objects in place in 3D space and
drawing them in the right order. The drawing pipeline works as follows:

In C3DRenderer:
- Rotate objects to the correct position according to the camera
- Sort objects to be drawn from back to front (painter's algorithm)
- Command MObject-derived objects to draw themselves

In CPolygonObject (which is derived from M3DObject)
- Rotate polygon's corner points (vertices) to the correct position
- Clip polygons against view frustum (might increase or decrease triangle
  count)
- Sort polygons to be drawn from back to front (painter's algorithm)
- Draw polygons

By default, the only 3D object type implemented is a polygon object which
consists of textured triangles. Any types of 3D objects can be implemented -
for example, light balls which are only zoomed sprites. The parking lot is
tiled with asphalt-type tiles and the car is created with five objects: the car
body and four wheels that can be moved and tilted independently.

For sorting objects and polygons, an implementation of Quick Sort is used.
Rotation is implemented with matrix multipliers, and clipping against frustum
uses a dot product between plane normals and clipped vertex.

The engine uses two methods to draw the buffer to the physical screen.
- CFbsBitmap's BitBlt function, which is always a safe method
- Straight memory copy from draw buffer to screen memory, which is fast

The BitBlt method is always used on an emulator and whenever there is
something else besides the game on the screen (such as the "Charging" window). The memory
copy method is used when the whole screen is utilized by the game on the target
hardware.

The engine uses the CIdle timer to provide timing for the game. It gives all idle
time from the operating system to the game, so it is as fast as possible
without interfering with the operating system, especially the UI.

Sensor-related classes:
- CRRSensorApi provides access to sensors.
- TRRSensorInfo provides information about sensors.
- MRRSensorDataListener provides the callback function that enables listening for sensor data.
- TRRSensorEvent provides the actual data from the sensors.

The most important Symbian/S60 APIs in this example are:
- OpenGL ES API for drawing 3D objects
- CIdle for timer
- Math for algorithms 
- CImageDecoder to load textures
- CAknKeySoundSystem to disable key tones
- Sensor plug-in API for sensor-related functionality.


SENSOR FEATURES
-------------------------------------------------------------------------------

This application demonstrates the usage of the S60 Sensor API. In
devices equipped with an accelerometer sensor, it can be used to control the car抯 movements
in the game.

This example application can be compiled in three different ways
when considering sensor support, using the definitions introduced in the .mmp file.

1) No sensor support:
Commenting the CONFIG_SENSOR_API_SUPPORT_ENABLED definition disables sensor support
from the compilation and thus you do not even need to install the S60 Sensor API.

2) Support for only devices with accelerometer:
Uncommenting the CONFIG_SENSOR_API_SUPPORT_ENABLED definition and commenting
the CONFIG_SENSOR_API_LOAD_DYNAMICALLY definition enables sensor support, statically
linking the S60 Sensor API in the compile time. This way API functions are
easier to call and calls are easier to understand, but the application cannot be
installed into devices where the accelerometer is not available because lacking
the S60 Sensor API library will cause a panic.

3) Support for both the devices with and without accelerometer:
Uncommenting the CONFIG_SENSOR_API_SUPPORT_ENABLED and 
the CONFIG_SENSOR_API_LOAD_DYNAMICALLY definitions enables sensor support, 
dynamically linking the S60 Sensor API in the run time. This enables
installation to devices where the accelerometer is not available but still
retaining sensor support in those devices that have the accelerometer.
However, this makes API function calls a bit more complex and 
somewhat awkward to understand.

Sensor support requires the RRSensorApi.lib library and the RRSensorApi.h header file.
These are included in the S60 3rd Edition, Feature Pack 2 SDK. For earlier SDKs, the
S60 Sensor API is needed to be installed as a plug-in available at Forum Nokia.

Function CGame::RegisterSensor() implements accelerometer sensor observer
registration which is needed before being able to read accelerometer data. It
registers the CGame class to be an observer for sensor data events.

Function CGame::UnregisterSensor() implements accelerometer sensor
unregistration which must be done when accelerometer data is not needed
anymore.

Function CGame::HandleDataEventL() is a callback function which is called by
the Sensor API when new sensor data is available.

CSensorDataFilter class implements a simple moving average data filter for
smoothing the raw sensor data values. This filtering is needed because the data
values from the physical accelerometer sensor contains random noise which
disturbs controlling the car.

Besides generic sensor on/off setting, the behavior of the example can be
further adjusted with two boolean member variables, iSensorSteeringMode and 
iSensorThrottleMode, in the CGame:Move() function. The variable values can be changed
at runtime from the game menu. The previous variable defines whether sensors
are used for steering the car, and the latter one defines whether sensors are
used for accelerating (see the function CGame::Move() for implementation
details).


KNOWN ISSUES
-------------------------------------------------------------------------------

Graphics need to be shown first in full杝creen mode before setting rect to partial
screen.

On the Nokia N91, the lower part of the screen flickers. This phenomenon has not
been detected on any other device.

RUNNING THE EXAMPLE
-------------------------------------------------------------------------------

The game starts in full-screen mode. The menu can be accessed normally with the
left softkey, and the right softkey is used for exit. Other keys are described 
below:

[2] or Up Arrow: throttle
[8] or Down Arrow: reverse
[4] or Left Arrow: left turn
[6] or Right Arrow: right turn
[1]: rotate camera clockwise (only if sensor support is disabled)
[3]: rotate camera counter-clockwise (only if sensor support is disabled)

Accelerometer driving controls can be enabled from the menu. Steering is then
controlled by turning the mobile phone. Throttle and brake are controlled by
tilting the phone forwards and backwards, respectively.


BUILD & INSTALLATION INSTRUCTIONS
-------------------------------------------------------------------------------

The source code can be compiled on S60 3rd Edition SDKs. Additionally, the
S60 Sensor API is needed as a plug-in if not included in the SDK.
(S60 3rd Edition Feature Pack 1 and below do not contain the S60 Sensor API.)

See the above topic SENSOR FEATURES for additional information about the
compilation options for sensor support.

Steps for building and installing the application to a device are as follows:

Extract the example into the same drive as the SDK, and use command prompt
to compile the project.

Mobile device
~~~~~~~~~~~~~

1. Make sure the paths in .pkg files match those on your system.

2. Build:

    To build for target device (gcce):
    cd group
    bldmake bldfiles
    abld reallyclean gcce
    abld build gcce urel
or
    To build for target device (armv5):
    cd group
    bldmake bldfiles
    abld reallyclean armv5
    abld build armv5 urel

3. Make the sis:

    cd Install
    createsis create Example3D_S60_3_0_v_1_2_0.pkg

4. Install the signed .sis file to an S60 3rd Edition device.
   - If you get a "Certificate error" during the installation of a self-signed 
     package, check that App.Manager -> Settings -> Software Installation is 
     set to "All."

Notes:
- Files in the data folder need to be copied to the emulator's
  \epoc32\winscw\c\private\e01FF1d0 folder before use. This should be done
  automatically if you have used bld.inf correctly.
- If you want to build a sis file that has an icon with Carbide, run bldmake bldfiles + abld
  resource from the command line (see above) before building from Carbide IDE and
  uncomment the mif icon row in the carbide .pkg file.

Emulator (WINSCW)
~~~~~~~~~~~~~~~~~

1. Compile the example:

    cd group
    bldmake bldfiles
    abld reallyclean winscw
    abld build winscw udeb

2. Start the emulator.


COMPATIBILITY
-------------------------------------------------------------------------------

S60 3rd Edition, FP2
S60 3rd Edition, FP1
S60 3rd Edition

V1.2 was tested with the following devices with accelerometer support:
Nokia N95 and Nokia N95 8GB. 
Note that a firmware update may be needed to get the sensor support into these devices. 
Read more at: http://wiki.forum.nokia.com/index.php/Sensor_API.

V1.2 was tested with the following devices without accelerometer support:
Nokia 6220 Classic, Nokia E61i, and Nokia E90 Communicator.


VERSION HISTORY
-------------------------------------------------------------------------------

1.2    Accelerometer driving controls added using S60 Sensor API.

1.1    The following changes were made (based on detected problems on the Nokia
       N93 and Nokia N93i):
        - EPOCHEAPSIZE and EPOCSTACKSIZE were increased (definitions made in
          the .mmp file).
        - glGenTextures(1, &iGlTextureFont) line added to get font texture work
          on Nokia N93 and Nokia N93i.

1.0    Original version for S60 3rd Edition (ported from Symbian OS: 3D Game
       Engine Example). The ported version provides the following changes:
        - key sounds removed with the CAknKeySoundSystem API
        - container changed to use fullscape mode as default
        - support added for 24 and 32 bit color depth (EColor16MU and
          EColor16M)
        - TInt64::Low replaced with I64LOW-macro
        - CMdaImageFileToBitmapUtility changed to CImageDecoder in texture
          loading (in CPictureLoader.cpp)
        - the eglMakeCurrent OpenGL API call before eglSwapBuffers removed
        - own double buffering algorithm removed and OpenGL double buffering
          always used.


A separate example that supports S60 2nd Edition and Series 80 2nd Edition
is available at Forum Nokia < http://www.forum.nokia.com/info/sw.nokia.com/id/35df7fe6-91fa-4444-a00d-addb779e6580/Symbian_OS_3D_Game_Engine_Example_v1_2_en.zip.html>.


RELATED DOCUMENTATION
-------------------------------------------------------------------------------

Symbian OS: 3D Game Engine Example 
- For S60 2nd Edition and Series 80 2nd Edition 
S60 2nd Edition Feature Pack 2: OpenGL ES 3D Example 
S60 Platform: Introduction to 3D Graphics in C++ (with Example) v1.1

Introduction to the Sensor API:
http://wiki.forum.nokia.com/index.php/Sensor_API