@DATABASE AmigaMail
@NODE MAIN "XII-9: Making CDTV Titles That Work on Amigas"
@TOC "Table_of_Contents/XII"
by Ben Phister, CATS


In the coming months Commodore plans to begin delivery of the A570
drive.  This CD-ROM peripheral for the Amiga 500 and Amiga 500 Plus
should rapidly expand the installed base of CDTV-compatible players.
With over 3 million Amigas sold worldwide, the potential for the A570
is enormous.

The A570 presents exciting opportunities for CDTV developers.  It also
presents a certain number of challenges.  Great efforts have been made
to ensure compatibility of titles for both platforms.  However, there
are numerous differences between the CDTV and the A570: keyboard plus
mouse vs. remote control, TV sets in a living room vs. RGB monitors on
a desktop, Kickstart 2.04 vs. Kickstart 1.3, etc.

With the availability of the optional keyboard for CDTV players, many
users now attach a keyboard to their CDTV.  Other users have attached
CD-ROM peripherals to their Amiga 2000 or A3000 computers, and need
keyboard support from titles.

To ensure strong sales of your title on all the systems capable of
playing CDTV discs, your title should take advantage of the new
features of the A570, yet remain easy-to-use on the CDTV player.  This
article discusses the differences between the two systems, and presents
extensions to the CDTV User Interface Guidelines to allow titles to run
on both platforms.

@{" Physical Differences " link XII-9-1}
@{" Operating System Issues " link XII-9-2}
@{" Emulating the Remote Controller " link XII-9-6}
@{" Screen Design Issues " link XII-9-16}
@{" Three Levels of Support for the A570 " link XII-9-18}
@{" Conclusion " link XII-9-22}

@ENDNODE

@NODE XII-9-1 "Physical Differences"
The A570 does not include the following items found on the CDTV player:

    * Infrared remote control.
    * Audio CD control buttons (Play, FF, etc.).
    * Fluorescent display.
    * Personal RAM Card slot.
    * RF or composite video output to TV or VCR.
    * MIDI ports.

Of course, functional equivalents of most of these items are already a
part of the Amiga 500; many others are available as options. Although
the Amiga lacks the standard CDTV resources above, the Amiga connected
to the A570 provides resources not available on all CDTVs.  Every title
running on an A570 will have access to a floppy disk drive and a
keyboard.  CDTV titles should support saving to a floppy, along with
saving to a personal RAM card.

@ENDNODE

@NODE XII-9-2 "Operating System Issues"

@{" Kickstart 1.3 vs. 2.04 " link XII-9-3}
@{" What Am I Running On? " link XII-9-4}
@{" Memory " link XII-9-5}

@ENDNODE

@NODE XII-9-3 "Kickstart 1.3 vs. 2.04"
The A570 connects to either an A500 running Kickstart 1.3 or 2.04, or
an A500 Plus running Kickstart 2.04.  It is imperative that your
application work in both these environments.  The A570 uses the
Kickstart ROM routines found in the host computer.  It contains its own
ROMs which provide the CDTV-specific functions (cdtv.device,
playerprefs.library, Audio control panel, CDTV Preferences, etc.)

@ENDNODE

@NODE XII-9-4 "What Am I Running On?"
It is possible for applications to detect if they are running on an
A570 or on a CDTV player.  There is an A570-specific module called
"A690ID".  A title can test to see if this module is present using the
exec.library function FindResident().  If the "A690ID" module is
present, the title is running on an A570-equipped A500.

@ENDNODE

@NODE XII-9-5 "Memory"
An Amiga with an A570 may have various amounts of RAM.  In a CDTV the
minimum memory configuration is 1 Mbyte of Chip RAM.  Do not assume
that all systems have the same memory configuration.  Some users might
try to run your application on an Amiga + A570 with only 512K of Chip
RAM and no Fast RAM.  Others may have a 512K Chip/512K Fast RAM system.
To avoid crashing due to memory shortages, check the amount of memory
available when your application begins execution.  If not enough memory
is available, you should display a message to that effect and stop
operating rather than crashing the machine.

Others may have more than 1 Mbyte of RAM: either Fast or Chip memory.
Your title should also work properly under these conditions.

@ENDNODE

@NODE XII-9-6 "Emulating the Remote Controller"
One of the major differences between the A570 and the CDTV is the
remote controller.  The Amiga's keyboard, the mouse, and, optionally,
the joystick replace the remote controller.  Your title must take these
differences into account, and your input handling routines may require
modification.  The following section will discuss these differences,
and make additions to the CDTV User Interface Guidelines.

Here is a chart describing how Amiga keyboard and mouse actions should
correspond to the CDTV player's remote controller buttons.


    Remote Controller   Amiga Keyboard         Amiga Mouse/Joystick
    -----------------   --------------         --------------------
     cursor buttons      Cursor keys              Mouse movement
  (directional arrows)

       'A' button       Left Alt + Left Amiga,     Left button
                        Left Amiga key alone,
                        F9 function key,
                        'A' key on keyboard

       'B' button       Right Alt + Right Amiga    Right button
                        Right Amiga key alone,
                        F10 function key
                        'B' key on keyboard

       0-9 buttons      Keyboard 0-9
                        Keypad number keys

         ESCAPE         Esc and Help
         ENTER          Return or keypad Enter
         REW            F1
         PLAY           F2
         PAUSE          F3
         FF             F4
         STOP           F5


@{" Cursor Buttons " link XII-9-7}             @{" Escape Key " link XII-9-10}                    @{" Genlock " link XII-9-13}
@{" The 'A' and 'B' Buttons " link XII-9-8}    @{" Help Key " link XII-9-11}                      @{" CD/TV " link XII-9-14}
@{" 0-9 Buttons " link XII-9-9}                @{" REW, PLAY, PAUSE, FF, STOP " link XII-9-12}    @{" JOY/MOUSE " link XII-9-15}

@ENDNODE

@NODE XII-9-7 "Cursor Buttons"
An application that runs on an A570 can emulate the four directional
arrow buttons on the CDTV remote control using two methods: via mouse
movements and via the four directional arrows next to the numeric
keypad.  Titles should support both methods of cursor control.  Jumping
highlights are easy to control using the arrow keys.  If the title has
a pointer, the user should be able to move it using the mouse, but, in
case the user doesn't have a mouse, titles should also allow the user
to move the pointer with the arrow keys.

@ENDNODE

@NODE XII-9-8 "The 'A' and 'B' Buttons"
The A and B buttons on the remote correspond to the left and right
buttons on the mouse.  If the user prefers to use a keyboard for input,
he can use any of the following:

    The left Alt/left Amiga combination for the 'A' button and right
    Alt/right Amiga for the 'B' button.

    The left Amiga key (raw keycode 66 hex) alone for 'A', and right Amiga
    key (raw keycode 67 hex) alone for 'B'.

    The F9 function key (rawkey code 58 hex) for 'A' and F10 function key
    (rawkey code 59 hex) for 'B'.

    the A (for left) and B (for right) keys on the keyboard.

By offering a keyboard equivalent to the 'A' and 'B' button, users with
keyboards will not have to move their hands from the keyboard to the
mouse in order to confirm a selection.  It also avoids accidental
movements of the mouse when pressing the rodent's left or right button.

The F9 and F10 function keys were selected because of their convenient
location near the directional arrow keys on the keyboard.

Supporting the 'A' and 'B' keys on the keyboard is more complicated.
The 'A' or 'B' key on the keyboard cannot be equivalents for the
remote's A and B buttons during the input of a text string.  In other
situations, however, this mapping can be helpful to the neophyte user.

If a title uses the console device, it should support both uppercase
and lowercase ('A' and 'a').  Furthermore, the raw keycodes for the 'A'
and 'B' keys must always be translated via the active keymap to
determine the actual ASCII value.  The rawkeyconvert.c routines in the
ROM Kernel manual give an example of this translation process.

If your title reads raw keycodes directly, beware of using raw keycodes
for the 'A' and 'B' keys on the keyboard, as the raw keycodes may
change if the user has a French keyboard.  The French keyboard has
reversed the position of the 'A' and the 'Q' keys.  If you choose to
have raw keycode support, you should accept both the 'A' (raw keycode
20 hex) and 'Q' (raw keycode 10 hex) for the 'A' button, and 'B' (raw
keycode 35 hex) for the 'B' button.

@ENDNODE

@NODE XII-9-9 "0-9 Buttons"
The 0-9 and ENTER buttons located in the center of the remote are
replaced by the Amiga keyboard's numeric keypad.  The keycodes of the
remote represent those found on the keypad, the only difference being
the reversed physical layout of the keys:

                Remote              Numeric keypad

                1 2 3                   7 8 9
                4 5 6 0                 4 5 6
                7 8 9                   1 2 3
                                          0

Your code will probably not have to be modified to take this into
account, unless it displays 9 icons in a grid pattern, and wants the
user to type in a number corresponding to a certain position.  If you
support a jumping highlight (as suggested in the CDTV User Interface
Guidelines), this should not be a problem.

Your code should also support the 10 numeric keys on top of the
alphanumeric keyboard (just below the function keys) for input of
numbers.

@ENDNODE

@NODE XII-9-10 "Escape Key"
The ESCAPE key requires special attention with a keyboard.  On the CDTV
remote control, the ESCAPE key generates the ESCAPE rawkey code of 45
hex, the same code as on the A500's keyboard.  The CDTV User Interface
Guidelines recommend that titles use the ESCAPE button as a HELP key.

@ENDNODE

@NODE XII-9-11 "Help Key"
The A500 keyboard has a Help key, rawkey code 5F.  To run effectively
on both the CDTV and A500 with an A570, applications should support
both the Escape key and the Help key to obtain Help functions.  If an
application detects that the user has pressed either the Help key or
the Escape key on the Amiga keyboard, the application should provide a
help function to the user.

@ENDNODE

@NODE XII-9-12 "REW, PLAY, PAUSE, FF, STOP"
These keys are mapped by the A570 ROM to the F1 through F5 keys on the
Amiga keyboard.  The Audio Control Panel uses these equivalents to play
CD audio discs.  If a title detects a keypress on F1 through F5, it
should react as if the user had pressed the corresponding remote
control button.

Certain titles ported from the Amiga to the CDTV may have already
established alternate uses of the F1 through F5 keys on the keyboard.
Any such application that retains its mapping of the F1 through F5 keys
for its A570 version should clearly document these alternate key
mappings in its manual.

@ENDNODE

@NODE XII-9-13 "Genlock"
The Genlock button on the CDTV remote is for mode selection of an
optional video genlock device that can be installed in the CDTV.  This
button has no equivalent on the A570.  If you want to support this
feature in an application running on an A570, you cannot be sure that
the genlock used with the Amiga supports software control of mode
switching.  Again, mention this fact in the user manual.

@ENDNODE

@NODE XII-9-14 "CD/TV"
This button on the CDTV remote controller determines whether the
TV/monitor displays input from the CDTV or from the broadcast (or
cable) TV source.  This button has no equivalent on the A570.  If the
user has his Amiga connected to a TV set, his existing cabling handles
this switch-over.

@ENDNODE

@NODE XII-9-15 "JOY/MOUSE"
This button on the remote determines whether the remote's cursor
buttons respond as a joystick or as a mouse.  This is not necessary on
the Amiga + A570: to enter joystick mode, the user simply plugs a
joystick into the Amiga.  To enter mouse mode, he uses his mouse.

Some CDTV applications only support one mode or the other.  Titles
should support both modes, if possible.  If a title only supports
joystick mode and the title cannot be reasonably controlled from the
keyboard, you should indicate this on your packaging, as an Amiga +
A570 user might not have a joystick.

@ENDNODE

@NODE XII-9-16 "Screen Design Issues"
The typical CDTV user is sitting approximately 3 meters from his TV
set.  The typical A570 user will be sitting less than one meter from an
RGB monitor.  These differences require some foresight on the part of
your application.

@{" Fonts " link XII-9-17}

@ENDNODE

@NODE XII-9-17 "Fonts"
For CDTV usage, a typical font should be no less than 18 points high.
This permits the user to easily view text from a distance.  An A570
user might prefer a smaller font in order to have more text on the
screen, especially when using text-based applications.  In this case,
an application should offer a selection of at least 2 different-sized
fonts to the user.

@ENDNODE

@NODE XII-9-18 "Three Levels of Support for the A570"
Full support for the A570 implies numerous constraints for the CDTV
developer.  He has to worry about supporting a keyboard, working with
different versions of the operating system, dealing with varying memory
configurations and working around differences between Amiga and CDTV
displays.  The issues of starting, exiting, and multitasking titles
remain.

There are several Amiga/CDTV configurations that may be booted into a
CLI or Workbench environment: Amiga + A570, any Amiga computer equipped
with a CD-ROM, and a CDTV player with a floppy or hard disk attached.
In these cases, the user may want to launch a CDTV title from that
environment.  If he does so, he will expect the title to exit cleanly,
release all memory, remove any special assigns that may have been
executed, etc.

Users may even want to multitask a title.  Most Amiga applications may
be multitasked, and the user may well expect the same from a CDTV
title.  Reference titles would be significantly enhanced if they
supported cutting-and-pasting directly into another application like a
word processor.  Those developing dictionary and encyclopedia titles
may want to provide access methods for users or other applications to
search on a key word.  Some may even want to add an ARexx port.

These issues, while reasonable requests from a user, add significant
new burdens to the developer.  Many CDTV titles are designed to take
over the machine.  Many of these titles require all the memory
available in the system (and even more, in some cases).  They often
make special assigns for fonts, data, etc.  Many include no clean-up
code.

Full compliance to AmigaDOS standards may be unreasonable for some
titles.  To address this problem, we have established three levels of
compatibility for CDTV titles running on Amigas: Minimal Support,
Support For Workbench Startup and Exit, and Full Multitasking Support.

@{" Level One-Minimal Support " link XII-9-19}
@{" Level Two-Support For Workbench Startup and Exit " link XII-9-20}
@{" Level Three-Full Multitasking Support " link XII-9-21}

@ENDNODE

@NODE XII-9-19 "Level One-Minimal Support"
An application that meets Level One support requires only a few
enhancements from a standard CDTV-only title.

  1) Supports input from the keyboard and the mouse.

  2) Runs under both Release 1.3 and Release 2 of the operating system
  (which is expected of all CDTV titles).

  3) Includes a way for the user to start the title from a CLI and the
     Workbench.  Such a title may reboot the system when it starts up.
     It may take over the entire system, refuse to multitask with other
     programs, have no cleanup code, and never exit.

Commodore has developed a standard icon and associated code, called
BootCD, which developers may include on their CDTV disc.  This icon
will appear from the Workbench.  If the user double-clicks it, a
message will appear telling the user to remove any floppy disks from
the drive, and warning that pressing the Continue gadget will reboot
the system.  If the user continues, BootCD will reset the system, and
the system will then boot directly from your title on CD-ROM.

@ENDNODE

@NODE XII-9-20 "Level Two-Support For Workbench Startup and Exit"
This level provides the user with a way to run CDTV applications
without rebooting the system.  A Level Two compliant title will also
return cleanly to the Workbench or the CLI when it is finished.  This
stage requires that a title:

  1) Supports input from the keyboard and the mouse.

  2) Runs under both Release 1.3 and Release 2.0 of the operating system.

  3) Launches from either the Workbench (via an icon) or the CLI.

  4) Manages any resources it allocates.

  5) Safely and Cleanly aborts in case any resource allocation fails.

  6) Cleans up properly upon exit, closing all libraries and devices, and
     returning all memory.

  7) Remembers the environment from which the user launched the title.
     If the user started the title from a CLI or Workbench, the title must
     be able to restore that environment cleanly.  If the title was booted
     directly from the CD-ROM, before exiting, the title should take
     precautions against leaving the system in an unusable environment.
     For example, if a title makes all of the Workbench colors black using
     the devs:system-configuration file, the user should not be allowed to
     return to the CLI or Workbench, as the user will only see a black
     screen.

In level two compatible titles, temporary assigns are acceptable.  The
application may assign system directories (such as fonts:, sys:, etc.)
to the CD during startup.  If it does so the title must restore any of
the assigns it reassigned.

A simple way to launch a title from a Workbench icon is using the IconX
utility.  This allows you to create a script that the system executes
when the user clicks on the program icon.  This script may contain any
assigns that a title requires.

An easy way a title can tell if the user booted directly from the
CD-ROM is checking for special command line arguments.  Imagine your
title is called ``MyApp''.  When the user boots the system from the
CD-ROM, the startup-sequence launches the application by using a
special command line, for example: ``MyApp ss''.  The ``ss'' tells the
title that the system was booted from the CD-ROM.  If the user starts
the application from the CLI, he would simply type ``MyApp''.  A title
might even utilize another special command line option to tell if it
was launched from an IconX script (i.e. ``MyApp iconx'').  Using this
method a title can detect how the user started it and can choose an
appropriate exit plan.

@ENDNODE

@NODE XII-9-21 "Level Three-Full Multitasking Support"
A title conforming to Level Three support allows users to multitask
freely (given sufficient memory).  These titles must include support
for points 1) through 7) above.  Furthermore, Level Three titles may
not re-assign any directory assigns that the system requires (i.e.
fonts:, sys:, s:, etc.).

If a title in this category needs to access a particular font on the
CD-ROM, it should not re-assign fonts: to cd0:fonts.  Instead, it
should refer to the full path name of the CD via the volume name of the
disc (for example, MyDisk:Data/MyFile).  You should not refer to the
device name (cd0:) since this may vary, either with more than one
CD-ROM peripheral attached, or a different device name for a
third-party drive.

If your title does refer to a volume name, be careful when
pre-mastering the title.  Make sure you enter the correct volume name
when running the ISO utility.  If another company does the
pre-mastering for you, make sure they use the correct volume name.

@ENDNODE

@NODE XII-9-22 "Conclusion"
Full support for the A570 does require a certain amount of effort on
behalf of the CDTV developer.  Many of these points are also relevant
for those CDTV owners that expand their unit to be an Amiga.

Remember, you are not obliged to support all these features.  Many CDTV
applications take over total control of the system, and are not
designed to multitask.  There is nothing wrong with doing this, even if
you want your title to run on the A570.  If you include Level One
support, you can insist that your title be booted directly from the CD.
It is better to have a title which runs perfectly on the CDTV than one
which is awkward to use on both the CDTV and the A570.

@ENDNODE
