README.MacOSX
author Sam Lantinga <slouken@libsdl.org>
Mon, 02 Jun 2003 14:50:22 +0000
changeset 632 85e104fe14c2
parent 221 50620ec9c86a
child 869 ae4ab3ac89a9
permissions -rw-r--r--
Date: Sun, 1 Jun 2003 15:38:45 -0700 (PDT)
From: Jeff Brown <jabrown@caida.org>
Subject: [patch] SDL-1.2.5 + FreeBSD joystick axes, hat fixes

Hello again! When I sent in some SDL fixes last December, I found out
they'd already been fixed in the CVS version. This time, I checked the
repository before bugging you. =)

I'm using SDL-1.2.5 on a FreeBSD 4.6.2-RELEASE system, and in the course
of getting my multi-analog-axis USB controller (with a hat switch!)
working with d2x-sdl -- the SDL port of the Descent 2 engine -- I came
across a few problems:

1) The second analog stick is reported as a slider in one direction, and
"Rz" in the other. SDL was ignoring the Rz axis, so I added Rx/Ry/Rz to
the set of things SDL considers to be axes.

2) After the above change, the set of JOYAXE_* axes for my gamepad was
{0,1,3,7}; however, d2x-sdl expects the axes to be contiguously numbered
from 0, which seems like a pretty reasonable expectation, rather than
having to scan the entire space of axes that SDL may or may not have.
So, I added a table lookup which maps the JOYAXE_* axis numbers to 0,1,...
in the order they're detected by SDL_SYS_JoystickOpen(), when reporting
them to the application. I also added a function "usage_to_joyaxe()"
which maps the USB HUG_* usage values to JOYAXE_values, since the repeated
case statements testing for HUG_* were getting out of hand.

3) The BSD joystick driver had no hat support, so I added it. It looks
like our USB library can only support one hat switch per device, which
makes life easy.

The patch against SDL-1.2.5 which implements these changes is at:

http://www.caida.org/~jabrown/patches/sdl-1.2.5-bsdhat.diff

After applying, SDL's "testjoystick" reports all activity from my gamepad
correctly, and d2x works too (though it needed some other fixes).

Moving on...

There is also a problem with slightly different USBHID library interfaces
on different versions of FreeBSD. I wasn't going to mention this since the
FreeBSD port for SDL-1.2.5 (and not SDL itself) was doing the FreeBSD
version-specific patching, so I e-mailed the port maintainer with this
change. However, I see that you've incorporated the FreeBSD
version-checking stuff into the CVS version of SDL, so now it's relevant
for you too.

The problem is, the FreeBSD #if tests don't work right for FreeBSD
4.6.2-RELEASE. There may be other versions with this problem, but I've
only tested 4.6.2-R. The following patch against your latest CVS version
fixes this:

--- SDL_sysjoystick.c-1.16 Tue Apr 15 09:02:08 2003
+++ SDL_sysjoystick.c Sun Jun 1 15:10:28 2003
@@ -420,6 +420,8 @@
# else
len = hid_report_size(rd, repinfo[repind].kind, r->rid);
# endif
+# elif (__FreeBSD_version == 460002)
+ len = hid_report_size(rd, r->rid, repinfo[repind].kind);
# else
len = hid_report_size(rd, repinfo[repind].kind, &r->rid);
#endif


I hope this is all useful to you. I've been getting myself dizzy playing
Descent 2 with it, all morning!

-Jeff Brown


P.S. My USB controller is a Thrustmaster Firestorm Dual Analog 2. That's
probably irrelevant, but I threw it in for completeness.
slouken@0
     1
==============================================================================
slouken@0
     2
Using the Simple DirectMedia Layer with Mac OS X
slouken@0
     3
==============================================================================
slouken@0
     4
slouken@0
     5
These instructions are for people using Apple's Mac OS X (pronounced
slouken@0
     6
"ten").
slouken@0
     7
slouken@0
     8
From the developer's point of view, OS X is a sort of hybrid Mac and
slouken@0
     9
Unix system, and you have the option of using either traditional
slouken@0
    10
command line tools or Apple's IDE ProjectBuilder (PB).
slouken@0
    11
slouken@0
    12
To build using the command line, use the standard configure and make
slouken@0
    13
process:
slouken@0
    14
slouken@0
    15
	./configure
slouken@0
    16
	make
slouken@0
    17
	make install
slouken@0
    18
slouken@0
    19
(You may need to create the subdirs of /usr/local manually.)
slouken@0
    20
slouken@172
    21
To use the library once it's built, you essential have two possibilities:
slouken@172
    22
use the traditional autoconf/automake/make method, or use Apple's Project Builder.
slouken@172
    23
slouken@172
    24
==============================================================================
slouken@172
    25
Using the Simple DirectMedia Layer with a traditional Makefile
slouken@172
    26
==============================================================================
slouken@172
    27
slouken@221
    28
An existing autoconf/automake build system for your SDL app has good chances
slouken@221
    29
to work almost unchanged on OS X. However, to produce a "real" MacOS X binary
slouken@221
    30
that you can distribute to users, you need to put the generated binary into a
slouken@221
    31
so called "bundle", which basically is a fancy folder with a name like
slouken@221
    32
"MyCoolGame.app".
slouken@172
    33
slouken@221
    34
To get this build automatically, add something like the following rule to
slouken@221
    35
your Makefile.am:
slouken@172
    36
slouken@199
    37
bundle_contents = APP_NAME.app/Contents
slouken@199
    38
APP_NAME_bundle: EXE_NAME
slouken@199
    39
	mkdir -p $(bundle_contents)/MacOS
slouken@199
    40
	mkdir -p $(bundle_contents)/Resources
slouken@199
    41
	echo "APPL????" > $(bundle_contents)/PkgInfo
slouken@199
    42
	$(INSTALL_PROGRAM) $< $(bundle_contents)/MacOS/
slouken@172
    43
slouken@221
    44
You should replace EXE_NAME with the name of the executable. APP_NAME is what
slouken@221
    45
will be visible to the user in the Finder. Usually it will be the same
slouken@221
    46
as EXE_NAME but capitalized. E.g. if EXE_NAME is "testgame" then APP_NAME 
slouken@221
    47
usually is "TestGame". You might also want to use @PACKAGE@ to use the package
slouken@221
    48
name as specified in your configure.in file.
slouken@172
    49
slouken@221
    50
If your project builds more than one application, you will have to do a bit
slouken@221
    51
more.  For each of your target applications, you need a seperate rule.
slouken@172
    52
slouken@221
    53
If you want the created bundles to be installed, you may want to add this
slouken@221
    54
rule to your Makefile.am:
slouken@172
    55
slouken@199
    56
install-exec-hook: APP_NAME_bundle
slouken@199
    57
	rm -rf $(DESTDIR)$(prefix)/Applications/APP_NAME.app
slouken@199
    58
	mkdir -p $(DESTDIR)$(prefix)/Applications/
slouken@199
    59
	cp -r $< /$(DESTDIR)$(prefix)Applications/
slouken@172
    60
slouken@221
    61
This rule takes the Bundle created by the rule from step 3 and installs them
slouken@221
    62
into $(DESTDIR)$(prefix)/Applications/.
slouken@172
    63
slouken@221
    64
Again, if you want to install multiple applications, you will have to augment
slouken@221
    65
the make rule accordingly.
slouken@172
    66
slouken@0
    67
slouken@47
    68
==============================================================================
slouken@47
    69
Using the Simple DirectMedia Layer with Project Builder
slouken@47
    70
==============================================================================
slouken@0
    71
slouken@221
    72
These instructions are for using Apple's Project Builder IDE to build SDL
slouken@221
    73
applications.
slouken@0
    74
slouken@53
    75
- First steps
slouken@53
    76
slouken@53
    77
The first thing to do is to unpack the PBProjects.tar.gz archive in the
slouken@53
    78
top level SDL directory (where the PBProjects.tar.gz archive resides).
slouken@53
    79
Because Stuffit Expander will unpack the archive into a subdirectory,
slouken@53
    80
you should unpack the archive manually from the command line:
slouken@53
    81
	cd [path_to_SDL_source]
slouken@53
    82
	tar zxf PBProjects.tar.gz
slouken@53
    83
This will create a new folder called PBProjects, which you can browse
slouken@53
    84
normally from the Finder.
slouken@53
    85
slouken@47
    86
- Building the Framework
slouken@47
    87
slouken@47
    88
The SDL Library is packaged as a framework bundle, an organized
slouken@47
    89
relocatable folder heirarchy of executible code, interface headers, 
slouken@47
    90
and additional resources. For practical purposes, you can think of a 
slouken@47
    91
framework as a more user and system-friendly shared library, whose library
slouken@47
    92
file behaves more or less like a standard UNIX shared library.
slouken@47
    93
slouken@47
    94
To build the framework, simply open the framework project and build it. 
slouken@47
    95
By default, the framework bundle "SDL.framework" is installed in 
slouken@47
    96
~/Library/Frameworks. Therefore, the testers and project stationary expect
slouken@47
    97
it to be located there. However, it will function the same in any of the
slouken@47
    98
following locations:
slouken@47
    99
slouken@47
   100
    ~/Library/Frameworks
slouken@47
   101
    /Local/Library/Frameworks
slouken@47
   102
    /System/Library/Frameworks
slouken@47
   103
slouken@47
   104
- Build Options
slouken@47
   105
    There are two "Build Styles" (See the "Targets" tab) for SDL.
slouken@47
   106
    "Deployment" should be used if you aren't tweaking the SDL library.
slouken@47
   107
    "Development" should be used to debug SDL apps or the library itself.
slouken@47
   108
slouken@47
   109
- Building the Testers
slouken@47
   110
    Open the SDLTest project and build away!
slouken@47
   111
slouken@47
   112
- Using the Project Stationary
slouken@47
   113
    Copy the stationary to the indicated folders to access it from
slouken@47
   114
    the "New Project" and "Add target" menus. What could be easier?
slouken@47
   115
slouken@47
   116
- Setting up a new project by hand
slouken@47
   117
    Some of you won't want to use the Stationary so I'll give some tips:
slouken@47
   118
    * Create a new "Cocoa Application"
slouken@207
   119
    * Add src/main/macosx/SDLMain.m , .h and .nib to your project
slouken@47
   120
    * Remove "main.c" from your project
slouken@47
   121
    * Remove "MainMenu.nib" from your project
slouken@47
   122
    * Add "$(HOME)/Library/Frameworks/SDL.framework/Headers" to include path
slouken@47
   123
    * Add "$(HOME)/Library/Frameworks" to the frameworks search path
slouken@207
   124
    * Add "-framework SDL -framework Foundation -framework AppKit" to "OTHER_LDFLAGS"
slouken@207
   125
    * Set the "Main Nib File" under "Application Settings" to "SDLMain.nib"
slouken@47
   126
    * Add your files
slouken@47
   127
    * Clean and build
slouken@47
   128
slouken@47
   129
- Building from command line
slouken@47
   130
    Use pbxbuild in the same directory as your .pbproj file
slouken@47
   131
         
slouken@47
   132
- Running your app
slouken@47
   133
    You can send command line args to your app by either invoking it from
slouken@47
   134
    the command line (in *.app/Contents/MacOS) or by entering them in the
slouken@47
   135
    "Executibles" panel of the target settings.
slouken@47
   136
    
slouken@47
   137
- Implementation Notes
slouken@47
   138
    Some things that may be of interest about how it all works...
slouken@47
   139
    * Working directory
slouken@191
   140
        As defined in the SDL_main.m file, the working directory of your SDL app
slouken@47
   141
        is by default set to its parent. You may wish to change this to better
slouken@47
   142
        suit your needs.
slouken@47
   143
    * You have a Cocoa App!
slouken@47
   144
        Your SDL app is essentially a Cocoa application. When your app
slouken@47
   145
        starts up and the libraries finish loading, a Cocoa procedure is called,
slouken@47
   146
        which sets up the working directory and calls your main() method.
slouken@47
   147
        You are free to modify your Cocoa app with generally no consequence 
slouken@47
   148
        to SDL. You cannot, however, easily change the SDL window itself.
slouken@47
   149
        Functionality may be added in the future to help this.
slouken@207
   150
	
slouken@207
   151
slouken@0
   152
Known bugs are listed in the file "BUGS"