Allegro Manual: MacOS X specifics

# MacOS X specifics

- DIGI_*/MacOSX — Supported MacOSX digital sound drivers.
- GFX_*/MacOSX — Supported MacOSX graphic drivers.
- MIDI_*/MacOSX — Supported MacOSX MIDI sound drivers.

In terms of file redistribution, the MacOS X platform behaves practically the same as the DOS platform. Read section chapter "Dos specifics" in the manual to learn more about this.

Allegro programs under MacOS X are Cocoa applications; in order to hide all the Cocoa interfacing to the end-user, you need to add the END_OF_MAIN() macro right after your main() function. This is a necessary step: if you omit it, your program will not compile.

The END_OF_MAIN() macro simply does some magic to make sure your program executes another function before your main(); this function is defined into the liballeg-main.a static library, which is automatically linked if you use the allegro-config script when linking. Otherwise be sure you link against it unless you want to get undefined symbol errors.

To behave nicely with the MacOS X user interface, Allegro apps will provide a standard application menu with the "Quit" menu item in it. The default behaviour when the user hits Command-Q or selects "Quit" is to do nothing. To override this behaviour you must call the set_close_button_callback() function; under MacOS X the supplied callback will be used either if the user clicks the window close button either on Command-Q or "Quit" selection. In this last case the application will not shutdown, but you are supposed to set some quit flag in your callback and check for it on a regular basis in your main program loop.

If you would like to use InterfaceBuilder to design a more fully-featured menu, Allegro will automatically load it if you create a bundle for your application. The use of InterfaceBuilder is beyond the scope of this document. Briefly, you need to create a Nib, called MainMenu.nib, containing a main menu and a controller. Then, when you create the bundle, install MainMenu.nib into the Contents/Resources subdirectory. Note that the actions attached to the menu items will be called from a different thread than the one in which your Allegro code is running. Therefore you should not do any work there (especially, don't call Allegro functions.) Instead, set a variable, and test it in your main loop.

Drivers GFX_*/MacOSX
MacOS X Allegro supports the following card parameters for the set_gfx_mode() function:

- GFX_TEXT
  This closes any graphics mode previously opened with set_gfx_mode.
- GFX_AUTODETECT
  Let Allegro pick an appropriate graphics driver.
- GFX_AUTODETECT_FULLSCREEN
  Autodetects a graphics driver, but will only use fullscreen drivers, failing if these are not available on current platform.
- GFX_AUTODETECT_WINDOWED
  Same as above, but uses only windowed drivers.
- GFX_SAFE
  Special driver for when you want to reliably set a graphics mode and don't really care what resolution. See the set_gfx_mode() documentation for details.
- GFX_QUARTZ_FULLSCREEN
  Fullscreen exclusive mode, using the CGDirectDisplay interface. Supports only resolutions higher or equal to 640x480, and uses hardware acceleration if available.
- GFX_QUARTZ_WINDOW
  Windowed mode using QuickDraw in a Cocoa window.

> See also: set_gfx_mode.

Drivers DIGI_*/MacOSX
The MacOS X sound functions support the following digital sound cards:

>           DIGI_AUTODETECT      - let Allegro pick a digital sound driver
>           DIGI_NONE            - no digital sound
>           DIGI_CORE_AUDIO      - CoreAudio digital output (OS >= X.2 required)
>           DIGI_SOUND_MANAGER   - Carbon Sound Manager digital output

> See also: detect_digi_driver, install_sound, install_sound_input.

Drivers MIDI_*/MacOSX
The MacOS X sound functions support the following MIDI sound cards:

>           MIDI_AUTODETECT      - let Allegro pick a MIDI sound driver
>           MIDI_NONE            - no MIDI sound
>           MIDI_CORE_AUDIO      - CoreAudio MIDI synthesizer (OS >= X.2 required)
>           MIDI_QUICKTIME       - QuickTime Music Note Allocator MIDI output
>           MIDI_DIGMID          - sample-based software wavetable player

> See also: detect_midi_driver, install_sound, install_sound_input.

Back to contents