FreeLists / haiku-doc / [haiku-doc] Diff files

[Mark-James McDougall <mj.mcdougall@xxxxxxxxx>]

Sorry I took so long, but attached is the diff files for the patches I 
submitted:
--
Mark-James McDougall (bulio)

/*!
\page compatibility Application Level API Incompatibilities with BeOS

\author Ingo Weinhold

Haiku R1 (x86) was designed and is currently being implemented to be binary and 
source 
compatible with applications written for BeOS R5 (x86) to a large extent, but 
not the other way around. In some cases we deliberately broke source 
compatibility while at the same time maintaining binary compatibility. Here are
some specific examples:

- The \c "be" header path is gone - it's called \c "os" in Haiku; since it is 
  always part of the default header search path anyway, you can always just 
  remove it to let your software compile on both platforms, ie. replace:
\code
#include <be/interface/View.h>
\endcode
  with: 
\code
#include <interface/View.h>
\endcode
  or rather use the preferred method of omitting the first part and use:
\code
#include <View.h>
\endcode

- BeOS contains a depreciated \c add-ons/TrackerAddons.h header, and a 
  header called \c add-ons/TrackerAddOns.h - Haiku only contains the 
  latter.
- Likewise, you'll find \c support/byteorder.h and \c support/ByteOrder.h
  in BeOS; Haiku only has ByteOrder.h.
- If you have subclassed BString and if you are using its \c _privateData 
  member, you should take note that it has been renamed to \link 
BString::fPrivateData
  fPrivateData \endlink.  However, it is now depreciated, and it might even be 
  made private in the future.
- The undocumented functions defined in Alias.h from the storage kit are not 
implemented.
- The private Device Map API (used by OpenTracker) has been replaced by a 
  different API, named the Disk Device API.
- The application debugging interface is conceptually similar, but is 
nevertheless
  both source and binary incompatible with BeOS R5.
- The file system API has changed; file systems that work on BeOS will no 
  longer work on Haiku.
- In several places we also dropped compatibility support for older BeOS 
  versions (PR2, R3, R4), which BeOS R5 still featured.
*/

/*!
\page midi1 The old Midi Kit (libmidi.so)

The old Midi Kit, or midi1 for short, dates all the way back to DR8, when BeOS 
only ran on BeBoxen hardware. Fortunately for us, it is documented quite well:

- <A HREF="http://bang.dhs.org/be/bebook/The%20Midi%20Kit/index.html";>Midi 
Kit chapter in the online Be Book</A>
- <A 
HREF="http://web.archive.org/web/20010618100542/www-classic.be.com/developers/developer_library/midi_kit.html";>Midi
 
Kit section of the old Be Developer Library</A>
- Be Newsletter Volume 1, Issue 49 - Introduces the MIDI synth
- Be Newsletter Volume 1, Issue 52 - Follow-up on issue 49
- Be Newsletter Volume 1, Issue 91 - How to use BSynth
- Be Newsletter Volume 1, Issue 102 - Axe sample code
- Be Newsletter Volume 1, Issue 104 - How to use BMidiPort
- Be Newsletter Volume 2, Issue 23 - EdMidi sample code
- Be Newsletter Volume 2, Issue 37 - How to use the MIDI synth
- Be Newsletter Volume 3, Issue 37 - Whistle sample code

To summarize, there are four basic MIDI classes:

- BMidi is the base class for most other classes from the Midi Kit
- BMidiPort can talk to a MIDI hardware port
- BMidiStore can read, write, and perform Standard MIDI files
- BMidiText is a debugging aid that dumps MIDI messages to <CODE>stdout</CODE>

The following classes allow you to use the Midi Kit's General MIDI synthesizer:

- BSynth controls the synthesizer
- BMidiSynth connects a BMidi object to the synth
- BMidiSynthFile connects a MIDI file to the synth
- BSamples lets you access the synth's sound data stream

To make a MIDI data stream through your application, you need to create a 
"network" of 
BMidi-derived objects that send and receive MIDI messages.

The old Midi Kit is slowly fading into obscurity. You may want to use the
\ref midi2 "new kit" instead. Also, please note that the Haiku implementation
of the kit sometimes behaves differently than the one from BeOS R5 or what
the BeBook says, but this is usually for the better.

The the synth classes are not completely functional, but are functional enough 
to play back General MIDI tunes. They should be backwards compatible with the
majority of BeOS MIDI applications. Not all methods of BSynth, BMidiSynth,
and BMidiSynthFile are implemented because some of them are rather obscure. 
BSamples is a complete no-op; in other words, with the Haiku Midi Kit 
you cannot push waveform data into the output stream of the softsynth.
*/