_____                         ________   ____    __  __
/\  __`\                      /\_____  \ /\  _`\ /\ \/\ \
\ \ \/\ \  _____     __    ___\/____//'/'\ \ \/\ \ \ \/'/'
 \ \ \ \ \/\ '__`\ /'__`\/' _ `\   //'/'  \ \ \ \ \ \ , <
  \ \ \_\ \ \ \L\ \\  __//\ \/\ \ //'/'___ \ \ \_\ \ \ \\`\
   \ \_____\ \ ,__/ \____\ \_\ \_\/\_______\\ \____/\ \_\ \_\
    \/_____/\ \ \/ \/____/\/_/\/_/\/_______/ \/___/  \/_/\/_/
             \ \_\
              \/_/ SDL 1.3 for OpenZDK
              
===============================================================================
RELEASE NOTES

Revision: 0.1
Date:     5 November 2010
Author:   itsnotabigtruck
===============================================================================

-1. DOWNLOAD

Devkit w/ source: http://zunedevwiki.org/sdl/sdl_for_openzdk-rel1-20101105.zip
Example programs: Halló SDL | testdraw2 | testspriteminimal
Mercurial: http://petrograd.zunedevwiki.org/hg/

Documentation: http://wiki.libsdl.org/moin.cgi/FrontPage
License: http://www.gnu.org/licenses/lgpl-2.1.html

0. INTRODUCTION

Welcome to SDL for OpenZDK! This release is intended to speed up development
of 2D applications for the Zune HD as well as facilitate porting of existing
ones. As the iPhone provides highly similar hardware capabilities, close
compatibility with the iPhone port is expected.

SDL for OpenZDK provides on-screen rendering through a new OpenGL ES 2.0-
enabled renderer implementation. Especial support is provided for NVIDIA Tegra
shader binaries, as shaders cannot be compiled "on-the-fly" on the Zune HD.
Shader source is supported as a fallback for other platforms that do support
shader compilation, but aren't compatible with the NVIDIA binaries.

1. RENDERING PERFORMANCE

For optimum performance, all rendering should be done using textures and the
SDL_Render* family of functions. These functions directly wrap the underlying
OpenGL ES 2.0 renderer. Using the SDL 1.2 compatibility APIs will result in
all geometry being rendered on the CPU, then uploaded to the GPU as a texture
for every frame, resulting in highly suboptimal performance.

2. OPENGL INITIALIZATION

A number of limitations are imposed on OpenGL context creation:

  * The context is always created with a 32-bit color buffer, 16-bit depth
    buffer, and no stencil buffer. Specifying higher values for the relevant
    attributes will result in an error when the context is created.
  * Software rendering is not available. Specifying that software rendering
    must be used will result in an error when the context is created.
  * Multisampling is not available through the Zune HD's interface compositor.
    Requesting multisampling will result in an error when the context is
    created.
  * Double buffering cannot be disabled in OpenGL ES. Specifying that single
    buffering must be used will result in an error when the context is created.
  * OpenGL ES 2.0 is the only version of OpenGL available on the Zune HD.
    Requesting another version of OpenGL will result in an error when the
    context is created.
  * Only one OpenGL context can exist at a time. Attempting to create a second
    context will result in an error.

Vertical sync is enabled by default. To change this, use the
SDL_GL_SetSwapInterval function.

3. TEXTURE FORMATS

All texture formats supported by OpenGL ES with the GL_EXT_bgra extension are
available:

  * SDL_PIXELFORMAT_ABGR8888
  * SDL_PIXELFORMAT_ABGR4444
  * SDL_PIXELFORMAT_ABGR1555
  * SDL_PIXELFORMAT_BGR565
  * SDL_PIXELFORMAT_BGR24
  * SDL_PIXELFORMAT_ARGB8888
  * SDL_PIXELFORMAT_ARGB4444
  * SDL_PIXELFORMAT_ARGB1555
  * SDL_PIXELFORMAT_RGB565
  * SDL_PIXELFORMAT_RGB24

Additionally, experimental support for SDL_PIXELFORMAT_INDEX8 is provided.

4. WINDOW MANAGEMENT

Multiple windows are not supported. The window created will be full-screen
regardless of the flags passed to SDL_CreateWindow.

5. EXITING THE APPLICATION

Your application should exit soon after the Home button has been pressed. This
occurrence will be signaled to your application as a single SDL_QUIT event. No
other indication that the program is to exit is provided through SDL.

6. ACCELEROMETER

The Zune HD's accelerometer is exposed as a 3-axis joystick in the same manner
as the iPhone platform driver. Joystick axis readings for the accelerometer are
scaled to the range -2^16 + 1 to 2^16 - 1 (-0x7FFF to 0x7FFF). To convert these
values to units of g, multiply each reading by SDL_MAX_GFORCE / 0x7FFF.

7. TOUCH INPUT

Touch input is communicated to the application through the new SDL touch API.
No emulation of mouse events is currently done. Programmers should note that
touch events are NOT reported in display coordinates - they are scaled to the
range 0 to 2^16 - 1, such that the maximum and minimum coordinate values for
a touch point are the same regardless of the display resolution. The OpenZDK
driver provides basic tracking of touch points as they move across the screen;
for more sophisticated processing, use the ID value provided by the system in
your own implementation. More information is available in README.touch in the
source distribution.

8. KEYBOARD INPUT

Keyboard input is not currently implemented in any form. If text input is
required, use the ZDKSystem keyboard API exposed from the zdksystem.h OpenZDK
header file. More information is available at the Zune Dev Wiki documentation
pages <http://bit.ly/aUvLJv>.

9. VIEWPORT REORIENTATION

Viewport reorientation is not currently implemented due to the lack of a
standard SDL orientation API and required interdependencies between the
rendering module and platform-specific code. This will hopefully be added in a
future release.

10. BUILDING SDL

A project for Visual Studio 2008 is provided in the "openzdk" directory of the
source distribution. Information about the prerequisites needed to build
against OpenZDK are available on the Zune Dev Wiki <http://bit.ly/8Y12vq>.

11. KNOWN ISSUES

Line segments (SDL_RenderDrawLine), line strips (SDL_RenderDrawLines), and
rectangles (SDL_RenderDrawRect[s]) are currently drawn without the
lower-rightmost pixel. This issue does not affect solid quads
(SDL_RenderFillRect[s]), textured quads (SDL_RenderCopy), and points
(SDL_RenderDrawPoint[s]). If precise drawing of lines is required, draw an
additional point using SDL_RenderDrawPoint at the lower-rightmost vertex of the
primitive.

12. SUPPORTED IMAGE AND AUDIO FORMATS

The following image formats are enabled in SDL_image:

  * BMP
  * GIF
  * JPG
  * LBM
  * PCX
  * PNG
  * PNM
  * TGA
  * XCF
  * XPM
  * XV

The following audio formats are enabled in SDL_mixer:

  * WAV
  * AIFF
  * MP3 (via libmad)
  * MIDI (via TiMidity)
  * Ogg Vorbis (via Tremolo)
  * Numerous module file formats (via libmikmod)

MIDI playback requires that a patch set be uploaded to \Flash2\timidity on your
Zune. Such a patch set is available from the SDL web site.

Two separate builds of SDL_mixer are provided: one with MP3 playback enabled,
and one without. If you link to SDL_mixer_GPL.dll to use MP3 playback, you must
release your application under the GPL.