README-porting.txt
author Sam Lantinga <slouken@libsdl.org>
Sat, 27 Jul 2013 03:20:09 -0700
changeset 7526 6c0f0280149c
parent 7222 2435b221d77d
permissions -rw-r--r--
Fixed bug 1272 - Bogus numlock key up/down events being reported on MacOS X Vern Jensen The problem is that in certain situations I'm getting THREE keyUp/keyDown events when I push certain keys. In my event code I added: case SDL_KEYUP: printf("SDL KeyScanCode for KEYUP event: %d\n", event->key.keysym.scancode ); … and case SDL_KEYDOWN: printf("SDL KeyScanCode for KEYDOWN event: %d\n", event->key.keysym.scancode ); … The result of one test run where I push 2 keys and then release them is this: SDL KeyScanCode for KEYDOWN event: 92 // Pushed keypad 4 SDL KeyScanCode for KEYDOWN event: 83 // Pushed left shift SDL KeyScanCode for KEYUP event: 83 SDL KeyScanCode for KEYDOWN event: 225 SDL KeyScanCode for KEYUP event: 92 // Released keypad 4 SDL KeyScanCode for KEYDOWN event: 83 SDL KeyScanCode for KEYUP event: 83 SDL KeyScanCode for KEYUP event: 225 // Released left shift There *should* be only a total of 4 events above… 2 for each key being pushed, and 2 for each being released. But instead some bogus events for numlock being pushed/released are sent from SDL. These events did not occur. I did not push numlock. The value above for numlock is 83. Comments above show when I pushed each key. As you can see, when I push left shift, THREE events are instantly sent to my application, keyDown and then keyUp for numlock, and then the valid event for left shift (the key that was actually pushed). You could replace keypad 4 with pretty much any keyPad key and it'll still happen. You can also replace it with any arrow key and it'll happen. However, when trying it with normal letter keys on the main keyboard it didn't. It happens with other modifier keys too, not just left shift. The order in which the keys are pressed matter. For instance, if I do: 1) keypad 4 2) left shift 3) release left shift 4) release keypad 4 Then at step 2, I get the 3 events above (when there should be only one), but steps 3 and 4 work properly… I don't get extra keyUp/keyDown events for steps 3 or 4. Thereas if the order of steps 3 and 4 are reversed, I get the bogus extra events for numlock. Also, the problem can occur even when pushing just a single key by itself. If I push left shift, then keypad 4, then release left shift, then release keypad 4, then the following push of left shift will cause the bug. If I continue pushing and releasing left shift though, it won't happen again until I again involve keypad keys. --- Sam Lantinga According to the Apple documentation, NSNumericPadKeyMask is set for any arrow or numeric keypad event. Indeed this is what's happening. I verified that we get the correct events for the numlock key and the mod state gets set correcly, so it should be safe to remove this bogus code.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
7222
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
     1
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
     2
* Porting To A New Platform
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
     3
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
     4
  The first thing you have to do when porting to a new platform, is look at
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
     5
include/SDL_platform.h and create an entry there for your operating system.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
     6
The standard format is __PLATFORM__, where PLATFORM is the name of the OS.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
     7
Ideally SDL_platform.h will be able to auto-detect the system it's building
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
     8
on based on C preprocessor symbols.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
     9
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    10
There are two basic ways of building SDL at the moment:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    11
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    12
1. The "UNIX" way:  ./configure; make; make install
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    13
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    14
   If you have a GNUish system, then you might try this.  Edit configure.in,
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    15
   take a look at the large section labelled:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    16
	"Set up the configuration based on the target platform!"
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    17
   Add a section for your platform, and then re-run autogen.sh and build!
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    18
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    19
2. Using an IDE:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    20
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    21
   If you're using an IDE or other non-configure build system, you'll probably
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    22
   want to create a custom SDL_config.h for your platform.  Edit SDL_config.h,
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    23
   add a section for your platform, and create a custom SDL_config_{platform}.h,
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    24
   based on SDL_config.h.minimal and SDL_config.h.in
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    25
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    26
   Add the top level include directory to the header search path, and then add
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    27
   the following sources to the project:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    28
	src/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    29
	src/atomic/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    30
	src/audio/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    31
	src/cpuinfo/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    32
	src/events/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    33
	src/file/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    34
	src/haptic/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    35
	src/joystick/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    36
	src/power/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    37
	src/render/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    38
	src/stdlib/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    39
	src/thread/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    40
	src/timer/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    41
	src/video/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    42
	src/audio/disk/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    43
	src/audio/dummy/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    44
	src/video/dummy/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    45
	src/haptic/dummy/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    46
	src/joystick/dummy/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    47
	src/main/dummy/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    48
	src/thread/generic/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    49
	src/timer/dummy/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    50
	src/loadso/dummy/*.c
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    51
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    52
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    53
Once you have a working library without any drivers, you can go back to each
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    54
of the major subsystems and start implementing drivers for your platform.
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    55
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    56
If you have any questions, don't hesitate to ask on the SDL mailing list:
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    57
	http://www.libsdl.org/mailing-list.php
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    58
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    59
Enjoy!
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    60
	Sam Lantinga				(slouken@libsdl.org)
2435b221d77d Renamed documentation files to .txt and converted them to DOS line endings so they would open properly on all systems.
Sam Lantinga <slouken@libsdl.org>
parents: 6987
diff changeset
    61