_____ ________ ____ __ __ /\ __`\ /\_____ \ /\ _`\ /\ \/\ \ \ \ \/\ \ _____ __ ___\/____//'/'\ \ \/\ \ \ \/'/' \ \ \ \ \/\ '__`\ /'__`\/' _ `\ //'/' \ \ \ \ \ \ , < \ \ \_\ \ \ \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.