contrib/Mac_CFMCarbon/README.txt

   1 -----------------------------
   2 ODE - Mac CFM Carbon Port
   3 (contact Frank Condello <pox@planetquake.com> with questions regarding this port)
   4
   5 Although ODE contains a MacOSX makefile, and some individuals have implemented ODE in
   6 Cocoa, I opted to use (and prefer) CodeWarrior. This also opens up ODE to MacOS8 & 9
   7 users, without scarfing functionality in MacOSX (same binaries run on both platforms).
   8
   9 The 'ode_CW7.mcp' project contains release and debug targets to create static ODE and
  10 DrawStuff libraries.
  11
  12 'examples_CW7.mcp' contains targets for the entire ODE test suite, plus a couple other
  13 test programs which were posted to the ODE mailing list.
  14
  15
  16 -----------------------------
  17 Compiling Notes:
  18
  19 You'll need to extract the CodeWarrior projects from the 'CW7_projects.sit.bin' archive
  20 (They're nearly a meg uncompressed so this was done to be bandwith friendly on the CVS).
  21
  22 Projects require CodeWarrior 7 or above (recreating them with earlier versions shouldn't
  23 be too difficult). The projects use relative paths and are meant to be compiled from
  24 'contrib/Mac_CFMCarbon/'. Don't move them!
  25
  26 All the libraries build into the 'lib/' directory, all test applications build into
  27 'contrib/Mac_CFMCarbon/mac_testbin/' (and must be run from that directory since the
  28 texture path is hard-coded).
  29
  30 You'll need to compile the release ODE library, and the DrawStuff library before
  31 compiling the examples.
  32
  33 The ODE 'configurator' has not been ported, but a Mac-friendly 'config.h' header has been
  34 manually hacked together (all PPC Macs should be fine with this header). Single or double
  35 precision can be defined in the 'CommonPrefix.h' header found in
  36 'contrib/Mac_CFMCarbon/mac_source/'.
  37
  38 'contrib/Mac_CFMCarbon/mac_source/' also contains any mac specific additions to the main source.
  39 The directory structure here matches the main source tree, and I would recommend that this
  40 format is maintained when making additions, since the access paths are touchy (more below...)
  41
  42 Some issues were encountered with duplicate header names. CodeWarrior tends to be
  43 unforgiving about this sort of thing but fudging with the access paths eventually
  44 cleared up the problem. If ODE fails to compile, make sure the <ode/objects.h> and
  45 "objects.h" or <timer.h> and <Timer.h> are actually pointing to the correct header.
  46
  47 You'll need Apple's OpenGL SDK (with GLUT) in your compiler path to build DrawStuff. I've
  48 added redirection headers in 'contrib/Mac_CFMCarbon/mac_source/include/GL/' to properly
  49 link with the Apple headers (since the projects are set to follow DOS paths).
  50
  51 The examples link against a crapload of static libraries, but my initial builds using
  52 ODE, MSL, GLUT, and DrawStuff shared/merged DLL's proved unstable (mostly problems with
  53 SIOUX spawning multiple sessions, and crashes in Classic). Static libs just worked better
  54 in the end, but the test apps are a little bloated as a result, and need to be re-linked
  55 whenever a change to a library is made.
  56
  57 IMPORTANT: You must use the same 'CommonPrefix.h' settings for libraries, and test apps
  58 (i.e. double or single precision).
  59
  60
  61 -----------------------------
  62 Running the test apps:
  63
  64 The test apps will show the SIOUX CLI prompt when run. Just hit OK to ignore it, or add any
  65 DrawStuff arguments. You'll want to log output to a file for 'test_ode'.
  66
  67 There are two extra test programs in the 'mac_source' directory. Both were posted to the ODE
  68 mailing list by OSX users. 'test_stability1' visualizes some internal issues with ODE, and
  69 'test_stacktest' is a standalone GLUT program (doesn't use DrawStuff) that can be useful
  70 to stress test the library, and give you an idea of just how much stack memory you're
  71 going to need for large systems.
  72
  73 ISSUES:
  74
  75 The carbon DrawStuff lib uses GLUT to make life easy, but GLUT isn't exactly bug-free
  76 or stable on the Mac... Try moving the mouse around if a simulation is running slowly
  77 on OS9 (it's not ODE's fault, but rather a poor carbon GLUT implementation - seems GLUT stalls
  78 when it's not getting system events  - I haven't seen this problem on OSX).
  79
  80 The 3D view may not update if typing in the SIOUX console window.
  81
  82 You cannot pass startup args to GLUT due to the way the DrawStuff library initializes.
  83
  84 'Write Frames' doesn't actually do anything at the moment.
  85
  86 The 'test_joints' app seems broken (though I don't know what the intended effect should be)
  87
  88
  89 -----------------------------
  90 TODO:
  91
  92 - Re-add shared library targets (if stability issues are resolved).
  93 - Implement 'Write Frames' in DrawStuff.
  94 - Write a Carbon compatible configurator
  95 - Create CodeWarrior 8 projects (once I scrounge up enough dough for the update).