docs/README-ios.md
author Philipp Wiesemann <philipp.wiesemann@arcor.de>
Mon, 11 Aug 2014 23:13:20 +0200
changeset 9050 bc9616da37cd
parent 9025 d09d4b578e77
child 9064 428bff5bf38a
permissions -rw-r--r--
Fixed doxygen warning and markdown formatting.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     1
iOS
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     2
======
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     3
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     4
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     5
Building the Simple DirectMedia Layer for iPhone OS 5.1
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     6
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     7
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     8
Requirements: Mac OS X v10.5 or later and the iPhone SDK.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
     9
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    10
Instructions:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    11
1.  Open SDL.xcodeproj (located in Xcode-iOS/SDL) in XCode.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    12
2.  Select your desired target, and hit build.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    13
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    14
There are three build targets:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    15
- libSDL.a:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    16
	Build SDL as a statically linked library
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    17
- testsdl
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    18
	Build a test program (there are known test failures which are fine)
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    19
- Template:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    20
	Package a project template together with the SDL for iPhone static libraries and copies of the SDL headers.  The template includes proper references to the SDL library and headers, skeleton code for a basic SDL program, and placeholder graphics for the application icon and startup screen.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    21
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    22
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    23
Build SDL for iOS from the command line
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    24
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    25
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    26
1. cd (PATH WHERE THE SDL CODE IS)/build-scripts
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    27
2. ./iosbuild.sh
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    28
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    29
If everything goes fine, you should see a build/ios directory, inside there's
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    30
two directories "lib" and "include". 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    31
"include" contains a copy of the SDL headers that you'll need for your project,
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    32
make sure to configure XCode to look for headers there.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    33
"lib" contains find two files, libSDL2.a and libSDL2main.a, you have to add both 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    34
to your XCode project. These libraries contain three architectures in them,
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    35
armv6 for legacy devices, armv7, and i386 (for the simulator).
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    36
By default, iosbuild.sh will autodetect the SDK version you have installed using 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    37
xcodebuild -showsdks, and build for iOS >= 3.0, you can override this behaviour 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    38
by setting the MIN_OS_VERSION variable, ie:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    39
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    40
MIN_OS_VERSION=4.2 ./iosbuild.sh
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    41
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    42
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    43
Using the Simple DirectMedia Layer for iOS
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    44
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    45
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    46
FIXME: This needs to be updated for the latest methods
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    47
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    48
Here is the easiest method:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    49
1.  Build the SDL libraries (libSDL.a and libSDLSimulator.a) and the iPhone SDL Application template.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    50
1.  Install the iPhone SDL Application template by copying it to one of XCode's template directories.  I recommend creating a directory called "SDL" in "/Developer/Platforms/iOS.platform/Developer/Library/XCode/Project Templates/" and placing it there.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    51
2.  Start a new project using the template.  The project should be immediately ready for use with SDL.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    52
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    53
Here is a more manual method:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    54
1.  Create a new iPhone view based application.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    55
2.  Build the SDL static libraries (libSDL.a and libSDLSimulator.a) for iPhone and include them in your project.  XCode will ignore the library that is not currently of the correct architecture, hence your app will work both on iPhone and in the iPhone Simulator.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    56
3.  Include the SDL header files in your project.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    57
4.  Remove the ApplicationDelegate.h and ApplicationDelegate.m files -- SDL for iPhone provides its own UIApplicationDelegate.  Remove MainWindow.xib -- SDL for iPhone produces its user interface programmatically.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    58
5.  Delete the contents of main.m and program your app as a regular SDL program instead.  You may replace main.m with your own main.c, but you must tell XCode not to use the project prefix file, as it includes Objective-C code.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    59
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    60
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    61
Notes -- Application events
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    62
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    63
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    64
On iOS the application goes through a fixed life cycle and you will get
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    65
notifications of state changes via application events. When these events
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    66
are delivered you must handle them in an event callback because the OS may
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    67
not give you any processing time after the events are delivered.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    68
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    69
e.g.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    70
9050
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    71
    int HandleAppEvents(void *userdata, SDL_Event *event)
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
    72
    {
9050
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    73
        switch (event->type)
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    74
        {
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    75
        case SDL_APP_TERMINATING:
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    76
            /* Terminate the app.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    77
               Shut everything down before returning from this function.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    78
            */
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    79
            return 0;
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    80
        case SDL_APP_LOWMEMORY:
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    81
            /* You will get this when your app is paused and iOS wants more memory.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    82
               Release as much memory as possible.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    83
            */
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    84
            return 0;
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    85
        case SDL_APP_WILLENTERBACKGROUND:
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    86
            /* Prepare your app to go into the background.  Stop loops, etc.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    87
               This gets called when the user hits the home button, or gets a call.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    88
            */
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    89
            return 0;
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    90
        case SDL_APP_DIDENTERBACKGROUND:
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    91
            /* This will get called if the user accepted whatever sent your app to the background.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    92
               If the user got a phone call and canceled it, you'll instead get an SDL_APP_DIDENTERFOREGROUND event and restart your loops.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    93
               When you get this, you have 5 seconds to save all your state or the app will be terminated.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    94
               Your app is NOT active at this point.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    95
            */
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    96
            return 0;
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    97
        case SDL_APP_WILLENTERFOREGROUND:
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    98
            /* This call happens when your app is coming back to the foreground.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
    99
               Restore all your state here.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   100
            */
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   101
            return 0;
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   102
        case SDL_APP_DIDENTERFOREGROUND:
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   103
            /* Restart your loops here.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   104
               Your app is interactive and getting CPU again.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   105
            */
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   106
            return 0;
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   107
        default:
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   108
            /* No special processing, add it to the event queue */
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   109
            return 1;
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   110
        }
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   111
    }
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   112
    
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   113
    int main(int argc, char *argv[])
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   114
    {
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   115
        SDL_SetEventFilter(HandleAppEvents, NULL);
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   116
    
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   117
        ... run your main loop
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   118
    
9023
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   119
        return 0;
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   120
    }
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   121
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   122
    
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   123
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   124
Notes -- Accelerometer as Joystick
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   125
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   126
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   127
SDL for iPhone supports polling the built in accelerometer as a joystick device.  For an example on how to do this, see the accelerometer.c in the demos directory.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   128
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   129
The main thing to note when using the accelerometer with SDL is that while the iPhone natively reports accelerometer as floating point values in units of g-force, SDL_JoystickGetAxis reports joystick values as signed integers.  Hence, in order to convert between the two, some clamping and scaling is necessary on the part of the iPhone SDL joystick driver.  To convert SDL_JoystickGetAxis reported values BACK to units of g-force, simply multiply the values by SDL_IPHONE_MAX_GFORCE / 0x7FFF.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   130
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   131
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   132
Notes -- OpenGL ES
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   133
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   134
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   135
Your SDL application for iPhone uses OpenGL ES for video by default.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   136
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   137
OpenGL ES for iPhone supports several display pixel formats, such as RGBA8 and RGB565, which provide a 32 bit and 16 bit color buffer respectively.  By default, the implementation uses RGB565, but you may use RGBA8 by setting each color component to 8 bits in SDL_GL_SetAttribute.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   138
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   139
If your application doesn't use OpenGL's depth buffer, you may find significant performance improvement by setting SDL_GL_DEPTH_SIZE to 0.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   140
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   141
Finally, if your application completely redraws the screen each frame, you may find significant performance improvement by setting the attribute SDL_GL_RETAINED_BACKING to 1.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   142
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   143
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   144
Notes -- Keyboard
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   145
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   146
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   147
The SDL keyboard API has been extended to support on-screen keyboards:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   148
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   149
void SDL_StartTextInput()
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   150
	-- enables text events and reveals the onscreen keyboard.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   151
void SDL_StopTextInput()
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   152
	-- disables text events and hides the onscreen keyboard.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   153
SDL_bool SDL_IsTextInputActive()
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   154
	-- returns whether or not text events are enabled (and the onscreen keyboard is visible)
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   155
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   156
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   157
Notes -- Reading and Writing files
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   158
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   159
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   160
Each application installed on iPhone resides in a sandbox which includes its own Application Home directory.  Your application may not access files outside this directory.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   161
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   162
Once your application is installed its directory tree looks like:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   163
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   164
MySDLApp Home/
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   165
	MySDLApp.app
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   166
	Documents/
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   167
	Library/
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   168
		Preferences/
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   169
	tmp/
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   170
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   171
When your SDL based iPhone application starts up, it sets the working directory to the main bundle (MySDLApp Home/MySDLApp.app), where your application resources are stored.  You cannot write to this directory.  Instead, I advise you to write document files to "../Documents/" and preferences to "../Library/Preferences".  
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   172
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   173
More information on this subject is available here:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   174
http://developer.apple.com/library/ios/#documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/Introduction/Introduction.html
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   175
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   176
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   177
Notes -- iPhone SDL limitations
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   178
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   179
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   180
Windows:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   181
	Full-size, single window applications only.  You cannot create multi-window SDL applications for iPhone OS.  The application window will fill the display, though you have the option of turning on or off the menu-bar (pass SDL_CreateWindow the flag SDL_WINDOW_BORDERLESS).
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   182
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   183
Textures:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   184
	The optimal texture formats on iOS are SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_ABGR8888, SDL_PIXELFORMAT_BGR888, and SDL_PIXELFORMAT_RGB24 pixel formats.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   185
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   186
Loading Shared Objects:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   187
	This is disabled by default since it seems to break the terms of the iPhone SDK agreement.  It can be re-enabled in SDL_config_iphoneos.h.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   188
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   189
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   190
Game Center 
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   191
==============================================================================
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   192
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   193
Game Center integration requires that you break up your main loop in order to yield control back to the system. In other words, instead of running an endless main loop, you run each frame in a callback function, using:
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   194
    
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   195
int SDL_iPhoneSetAnimationCallback(SDL_Window * window, int interval, void (*callback)(void*), void *callbackParam);
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   196
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   197
This will set up the given function to be called back on the animation callback, and then you have to return from main() to let the Cocoa event loop run.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   198
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   199
e.g.
276802355854 Rearrange documentation
Gabriel Jacobo <gabomdq@gmail.com>
parents:
diff changeset
   200
9050
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   201
    extern "C"
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   202
    void ShowFrame(void*)
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   203
    {
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   204
        ... do event handling, frame logic and rendering
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   205
    }
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   206
    
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   207
    int main(int argc, char *argv[])
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   208
    {
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   209
        ... initialize game ...
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   210
    
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   211
    #if __IPHONEOS__
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   212
            // Initialize the Game Center for scoring and matchmaking
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   213
            InitGameCenter();
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   214
    
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   215
            // Set up the game to run in the window animation callback on iOS
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   216
            // so that Game Center and so forth works correctly.
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   217
            SDL_iPhoneSetAnimationCallback(window, 1, ShowFrame, NULL);
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   218
    #else
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   219
            while ( running ) {
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   220
                    ShowFrame(0);
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   221
                    DelayFrame();
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   222
            }
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   223
    #endif
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   224
            return 0;
bc9616da37cd Fixed doxygen warning and markdown formatting.
Philipp Wiesemann <philipp.wiesemann@arcor.de>
parents: 9025
diff changeset
   225
    }