README.RISCOS
author Sam Lantinga <slouken@libsdl.org>
Wed, 24 Aug 2005 21:57:48 +0000
changeset 1131 e044e7c70a50
parent 1035 974ba6ae0fa3
child 1332 de3d552b59b2
permissions -rw-r--r--
Merged the Visual C++ 6 and 7 projects so all Visual C++ users unpack the same set of projects to get started.
slouken@955
     1
Readme for RISC OS port of SDL
slouken@955
     2
==============================
slouken@955
     3
slouken@1035
     4
This document last updated on 26th January 2005
slouken@955
     5
slouken@1035
     6
This is a RISC OS port of the Simple Direct Media Layer (SDL) by Alan Buckley with contributions from Peter Naulls.
slouken@955
     7
slouken@955
     8
Details of the SDL can be found at http://www.libsdl.org.
slouken@955
     9
slouken@1035
    10
The source code including the RISC OS version can be obtained from
slouken@1035
    11
http://www.libsdl.org.
slouken@955
    12
slouken@955
    13
RISC OS makefiles, pre built libraries and many games and applications compiled for RISC OS using this library can be downloaded from The Unix Porting Project at http://www.chocky.org/unix/index.html.
slouken@955
    14
slouken@955
    15
This is released under the LGPL see the file COPYING for details.
slouken@955
    16
slouken@955
    17
slouken@1035
    18
RISC OS port of SDL runtime information
slouken@955
    19
======================================
slouken@955
    20
slouken@955
    21
Runtime requirements
slouken@955
    22
--------------------
slouken@955
    23
slouken@1035
    24
This library currently needs a minimum of RISC OS 3.6. The source code for the library (and a lot of the programs built with it) also need long file names.
slouken@955
    25
slouken@1035
    26
To use the audio you also need 16 bit sound and to have installed the DigitalRender module by Andreas Dehmel version 0.51 available from his
slouken@1035
    27
web site: http://home.t-online.de/~zarquon
slouken@1035
    28
This is loaded when needed by UnixLib.
slouken@955
    29
slouken@1035
    30
Note: As most programs ported from other OSes use high resolution graphics and a memory back buffer a machine with a StrongARM processor and 1 or 2MB of VRAM (or a better machine) is recomended.
slouken@955
    31
slouken@955
    32
slouken@1035
    33
RISC OS runtime parameters
slouken@955
    34
-------------------------
slouken@955
    35
slouken@1035
    36
Several environmental variables have been defined to make porting programs easier (i.e. By setting these variable you do not need to have source code differences between OSes).
slouken@955
    37
slouken@955
    38
They are all defined on an application basis.
slouken@955
    39
slouken@955
    40
The <appname> used below is found as follows:
slouken@955
    41
1. Use the name of the program unless it is !RunImage
slouken@955
    42
2. Check the folder specification for the folder !RunImage is run from. If it is a folder name use that name, otherwise if it is an environmental variable of the form <XXX$Dir> use the value of XXX.
slouken@955
    43
slouken@955
    44
The variables are:
slouken@955
    45
slouken@1035
    46
SDL$<appname>$TaskName - The name of the task for RISC OS. If omitted then <appname> is used for the task name,
slouken@955
    47
slouken@1035
    48
SDL$<appname>$BackBuffer - set to 1 to use a system memory back buffer for the screen in full screen mode. Some programs on other systems assume their is always a back buffer even though the SDL specification specifies this is not the case. The current RISC OS implementation uses direct writes to the screen if a hardware fullscreen is requested.
slouken@955
    49
slouken@955
    50
SDL$<appname>$CloseAction - set the action for the close icon. Again as programs don't match the specification you can set this to 0 to remove the close icon from the main window for applications where this does not affect the program.
slouken@955
    51
slouken@955
    52
SDL$<appname>$AudioBuffer - set the minimum size of the audio buffer in samples in steps of 512. If this is less than the minimum calculated from the parameters requested in the program by SDL_OpenAudio these will be used instead. If this parameter is not used or set to 0 the buffer size will be calculated to buffer 10 centisecond of sound. The time buffered can be calculated as specified size/frequency in seconds. The larger the buffer the more audio data that will be buffered, but this can lead to a lag between a sound being requested and it being heard, so the size should be kept to a minimum. You should only set this parameter if the sound is being missed out. 
slouken@955
    53
slouken@955
    54
slouken@955
    55
slouken@1035
    56
RISC OS SDL port API notes
slouken@955
    57
=========================
slouken@955
    58
slouken@955
    59
Current level of implementation
slouken@955
    60
-------------------------------
slouken@955
    61
slouken@955
    62
The following list is an overview of how much of the SDL is implemented. The areas match the main areas of the SDL.
slouken@955
    63
slouken@1035
    64
video - Mostly done. Doesn't cover gamma, YUV-overlay or OpenGL.
slouken@955
    65
Window Manager - Mostly done. SetIcon/IconifyWindow not implemented.
slouken@955
    66
Events - Mostly done. Resize and some joystick events missing.
slouken@955
    67
Joystick - Currently assumes a single joystick with 4 buttons.
slouken@1035
    68
Audio - Done
slouken@955
    69
CDROM - Not implemented.
slouken@955
    70
Threads - Done
slouken@955
    71
Timers - Done
slouken@955
    72
slouken@955
    73
Thread support can be removed by defining DISABLE_THREADS and recompiling the library.
slouken@955
    74
slouken@955
    75
SDL API notes
slouken@955
    76
-------------
slouken@955
    77
slouken@955
    78
This section contains additional notes on some specific commands.
slouken@955
    79
slouken@955
    80
SDL_SetVideoMode
slouken@1035
    81
  On RISC OS a fullscreen mode directly accesses the screen. This can be modified by the environmental variable (SDL$<appname>$BackBuffer) or by using the SDL_SWSURFACE flag to write to an offscreen buffer that is updated using SDL_UpdateRects.
slouken@955
    82
  Open GL is not supported so SDL_OPENGL and SDL_OPENGLBLIT flags fail.
slouken@955
    83
  SDL_RESIZEABLE and SDL_NOFRAME flags are not supported.
slouken@955
    84
slouken@955
    85
SDL_SetColors
slouken@1035
    86
  In a wimp mode the screen colours are not changed for a hardware palette instead the RISC OS sprite colour mapping is used to get the best matching colours.
slouken@955
    87
slouken@955
    88
SDL_CreateCursor
slouken@955
    89
   Inverted colour is not supported.
slouken@955
    90
slouken@955
    91
SDL_WM_ToggleFullScreen
slouken@955
    92
   Currently this won't work if the application starts up in Fullscreen mode.
slouken@955
    93
   Toggling to fullscreen will only work if the monitor is set up to support the exact screen size requested.
slouken@955
    94
slouken@955
    95
SDL_EnableUNICODE
slouken@955
    96
   Unicode translation used here is only really accurate for 7 bit characters.
slouken@955
    97
slouken@955
    98
SDL_NumJoysticks/JoystickName etc.
slouken@955
    99
   Hardcoded to expect only 1 joystick with 4 buttons if the Joystick module is loaded.
slouken@955
   100
slouken@955
   101
SDL_GetTicks
slouken@955
   102
   Timer used has only a centisecond accuracy. This applies to other time related functions.
slouken@955
   103
   
slouken@955
   104
SDL_Delay
slouken@955
   105
   Modified to poll keyboard/mouse during the delay on the event thread.
slouken@955
   106
slouken@955
   107
slouken@955
   108
Notes on current implementation
slouken@955
   109
-------------------------------
slouken@955
   110
slouken@955
   111
Keyboard and mouse are polled so if too long a time is spent between a call to SDL_PumpEvents, functions that use it, or SDL_Delay events can be missed.