Please consider a donation to the Higher Intellect project. See https://preterhuman.net/donate.php or the Donate to Higher Intellect page for more info.

Difference between revisions of "Apple Pippin"

From Higher Intellect Vintage Wiki
Jump to navigation Jump to search
Line 41: Line 41:
 
* 68k emulator
 
* 68k emulator
 
* [[Macintosh Toolbox]] intact  
 
* [[Macintosh Toolbox]] intact  
 +
 +
=Pippin Technical Notes=
 +
[[File:Devonly.gif|right]]
 +
 +
==Startup Process==
 +
===History===
 +
On all existing Macintosh computers, the boot process remains the same as it has been since the early days of the Macintosh. That startup process is as follows:
 +
 +
# After the loading of the Process Manager, the file name stored in the boot blocks as the startup application is launched.
 +
# After a standard format of a hard disk or floppy, this value is set to "Finder". So the Finder is launched as the main application.
 +
 +
On the initial Pippin, CD-ROMs developers were taught a simple way of setting up the startup application by modifying the boot blocks on the volume. While this worked as needed, it was a hack and is not an acceptable solution for shipping disks. It required the target application to be in the "blessed" System Folder, or in some cases, people made the root level of the volume the System Folder. This makes the disks very unattractive when the disk is used in a non-Pippin system (due to the need for the startup application to be in the System Folder). It could also cause problems with future Pippins as there would be more "unique" considerations that would need to be handled as the ROM attempts to override what is on the Pippin CD-ROMs.
 +
 +
===The New Pippin Way===
 +
The basic startup sequence has been modified for Pippin to allow additional flexibility and better aesthetics on non-Pippin Macintoshes. Further, the new startup process does not require any modification of the boot blocks.
 +
 +
At the point where the application stored in the boot blocks is launched, the startup process has been modified for Pippin purposes. If there is a file called "PippinFinder" in the System Folder, then it is launched. PippinFinder should only be used for developers that want to handle multiple applications per CD. For developers wanting to do this, please see the document regarding PippinFinder.
 +
 +
For single application titles, the startup process is simple. Create an alias to the application you want to launch and place it in the Startup Items folder. Also make sure that PippinFinder has been removed from the System Folder. That is all that is needed. The boot process with launch your application on the next launch rather then launching the Finder. And the final disk that is pressed will not contain the real Finder in the System Folder. The file named "Finder" will actually be just another copy of PippinFinder on final shipping CD-ROMs.
 +
 +
===Considerations for Developers===
 +
Pippin can have a variable amount of memory, but the size resource can only be configured once, so care should be made in setting this resource.
 +
 +
Pippin has been designed to use as little memory as possible. [[QuickTime]] that ships with all Macintoshes is much better in its memory allocation, using very little memory until QuickTime functionality is actually needed. The reason the memory allocation setting is important will become clear. If you have your preferred memory size set to a size which will use up all available application memory space then it means the system heap is unable to grow larger then it is after the startup process.
 +
 +
A better way of writing your application would be to utilize temporary memory more effectively. Make you application work well within a reasonable partition (2 MB) then utilize temporary memory as available. This would allow you application to work well on any memory configuration of Pippin. Will also allow the application to work more flexible on the entire Macintosh family as well.
 +
 +
If you application is configured to use all available memory, then any system extensions or managers that require system heap memory space will not function fully and in some cases not at all. To make sure you run well on all Pippins, you should do all your testing on the base model Pippin with no expanded memory.
 +
 +
===Launch Process Override for Developer Enabler===
 +
For developers, there is an override in the developer Enabler that allows them to override the above described boot process and go directly to the Finder. While booting, and before the extension loading has completed, hold down the "P" and "L" keys. This will allow the Pippin boot process to fall through and the boot to continue onto the Finder. If you have an alias in the Startup Items folder, the Finder will still attempt to launch the title in the Startup Items folder. This method will not work on shipping systems since the Finder on those machines is not a real Finder, but is another copy of PippinFinder.
 +
 +
==Pippin Standard File==
 +
===Introduction===
 +
When developing titles for the Pippin Power Player, many assumptions about storage that are typically made in the Macintosh environment must be slightly altered. Unlike a Macintosh, Pippin does not have a hard disk and the only guaranteed storage media available is 128k of internal NVRAM (non-volatile random access memory). An optional floppy disk drive could be installed as well, but this should not be assumed. Of the 128k built-in NVRAM, 8k is used by the system software, leaving 120k for general purpose storage. Obviously, assumptions made about file storage while working with virtually unlimited hard disk space are very different than working with a limited and relatively small amount of storage.
 +
 +
The following sections offer specific considerations for developers to keep in focus while developing new titles so they will be able to work effectively within Pippin storage limitations. In general, however, developers should build their titles with the intention of eliminating unnecessary storage, or saved data. With such a small amount of storage, utilizing available NVRAM as efficiently as possible is critical.
 +
 +
===Non-Volatile RAM (NVRAM)===
 +
The internal NVRAM is represented as a small HFS (Hierarchical File System) volume. By small HFS, this means that only two levels of hierarchy is allowed: the first level being the root level, the second level being folders appearing at the root level. In fact, within Pippin's NVRAM, folders can only appear at the root level, and no other folders are allowed within those folders. Nonetheless, despite this limited hierarchy, all normal file manager calls will treat NVRAM as a normal HFS disk.
 +
 +
===Single Folder Per Title===
 +
In order to reduce confusion, it is strongly recommended that developers save all files, preferences, and any other data in a single folder at the root level of either the NVRAM or a floppy disk. This folder would have a name closely related to the title name, and a name that would be included as a string resource. The title-named folder will provide organization for the user, and further simplify tasks such as copying, moving, and deleting files that are associated with particular a title.
 +
 +
===Preference Files===
 +
On the Macintosh, Preferences files are stored in the System Folder of the start-up disk. Since Pippin boots from a CD-ROM, dynamic Preferences files cannot be stored there. Therefore, if a title needs a writable Preferences file, it is suggested that the Preferences file also be stored in the title-named folder (see section 3). By ensuring that the Preferences file is of type "pref':" it does not also need to be displayed to the user.
 +
 +
===Pippin Standard File===
 +
Since the target audience for Pippin is not always computer users, the Macintosh Standard File is unnecessarily complex. New system software that simplifies the Standard File interface is provided on Pippin. Still, the new calls in the Pippin Standard File behave in a similar fashion to the Macintosh Standard File, and the main differences between the two is that the Pippin Standard File has larger colored icons, no "New Folder" button, and no "Desktop Button."
 +
 +
There are several new Pippin Standard file functions described in Pippin.h. PippinStandardGetFile, PippinStandardPutFile and PippinStandardDeleteFile are the three main functions:
 +
<pre>
 +
pascal void PippinStandardGetFile(FileFilterProcPtr filefilter
 +
short numTypes,
 +
SFTypeList typeList,
 +
StandardFileReply *reply);
 +
 +
pascal void PippinStandardPutFile(ConstStr255Param prompt
 +
ConstStr255Param defaultName,
 +
StandardFileReply *reply);
 +
pascal OsErr PippinStandardDeleteFile(long *bytesRequested);
 +
</pre>
 +
PippinStandardGetFile and PippinStandardPutFile in the Pippin Standard File work the same as StandardGetFile and StandardPutFile in the Macintosh Standard File. PippinStandardDeleteFile, however, is a new call in the Pippin Standard File which was created so files may be deleted while a title is running. This call does not allow copying or moving of files though. These tasks should be accomplished with the Pippin Navigation CD, which is included with each shipped Pippin unit.
 +
 +
The Pippin Standard File calls the title-named folder that is also specified in the "pipn" resource.
 +
 +
==Pippin Launch==
 +
===Introduction===
 +
The PippinFinder Technical Note describes the "replacement" Finder file for the Pippin System Folder, and that the actual code that drives a multiple application-interface is inside the Pippin Launch file. Apple provides an initial interface, a simple button interface, with the buttons changing appearance when they are selected. In summary, Pippin Launch is the file that PippinFinder uses, and this document is describing the "PCde" resource that Apple provides for developers to use. If you wish functionality beyond what PCde code implements, you will need to write your own code module. (See the "PippinFinder" Technical Note for details on how to create your own code module.)
 +
 +
Note: If you have a single-title CD and do not want to use a multiple-application interface via PippinFinder, you must ensure that the Pippin Launch file is removed from your System Folder on your Pippin CD. If not removed, you could cause problems with the boot process. The PCde module allows developers to easily customize the visual appearance of the Pippin startup environment when a Pippin CD is booted. The PCde module will only use the 2Meg provided to it via the PippinFinder. This is not of concern since it will all be disposed of before the title is launched.
 +
 +
To distinguish between the Apple provided PCDe module, and potential PCDe modules that may be created by developers, throughout the rest of this document, the Apple provided PCDe will be referenced as "ApplePCDe".
 +
 +
===PCde Interface Philosophy===
 +
The Launcher presents the user with a single window that contains a background picture and an arbitrary number of buttons.
 +
 +
The background can be a PICT of any size, although it is recommended that the PICT be 640 x 480 pixels in size so it will completely fill Pippin's screen, much like the Macintosh "desktop". If the PICT is not big enough to fill the entire screen, the remaining area will be filled with the black.
 +
 +
Each button is a rectangular PICT of any size. There are as many as three PICT resources associated with each button:
 +
 +
* one for the button that is un-highlighted
 +
* one for the button that is highlighted (used when the mouse is within the button rectangle if the resource is present)
 +
* one for the button that is in a "pressed" state (used when the user presses the mouse button when the mouse is within the button rectangle).
 +
 +
Each of these buttons should be the same pixel dimensions. Each, when present, are displayed at the coordinates of the button which are specified separately.
 +
 +
The behavior of the window is that, whenever the mouse is found to be within any of the buttons, the button's "highlighted" graphic is displayed (if it exists). If a "mouse within" sound exists, it is played as soon as the mouse is detected within the button rectangle. If the mouse leaves the highlighted button, the button's un-highlighted button graphic is again displayed. No mouse actions other than positioning movement is required by the user to get either graphical and audible feedback.
 +
 +
===Launcher Resource Overview===
 +
The resource fork of the Pippin Launch file contains all the data used by the ApplePCde. This includes all graphics and sound data, as well as small descriptive resources which tell the Launcher where to display buttons, how to highlight them, what sounds to play, etc. These resources can be edited with the resource editor ResEdit 2.1.3 (or higher) utility to create a custom launching environment for Pippin CDs.
 +
 +
There are only two types of resources that need to be created:
 +
 +
* a single "background" resource (i.e., pbkg)
 +
* some number of "button" resources (i.e., pbtn)
 +
 +
The following sections describe these resource types in more detail. Included in the resource fork of the Pippin Launch file on the Pippin Developer SDK CD are ResEdit "template" resources which simplify the creation of the background and button resources.
 +
 +
====The Background Resource====
 +
The background resource, pbkg, tells the Launcher which PICT resource are to be the background picture for the launcher's window. It also tells the Launcher which sound, snd, should be played when the Launcher first starts up. Only one pbkg resource should be present in the Launcher resource fork.
 +
 +
The contents of the pbkg resource are as follows:
 +
 +
Background PICT id - This is the resource ID of a PICT resource that is the background picture for the Launcher window. The dimensions of the PICT are used to set the size of the Launcher window.
 +
 +
Background PICT handle - This is used at runtime to hold a handle to the background picture and should not be filled in by the user. Reserved
 +
 +
Startup snd id - This is the resource ID of a snd resource. The sound, if specified, is played when the launcher starts up and can be used to play introductory music or instructions. Set this to zero if you don't want to use a startup sound.
 +
 +
====Button Resources====
 +
There can be any number of button resources present (i.e., any number of the resource pbtn). Each describes where a button is placed in the window, whether it is a hot highlighted or un-highlighted graphic, whether it is a "pressed" graphic, and what sounds should be played for the "mouse entering the button" and "mouse pressing the button" events.
 +
 +
The contents of the pbtn resource are as follows:
 +
 +
'''Button rectangle''' - This is used to specify the top left coordinates of the position of all button art for the button. The bottom and right members of the rectangle are ignored by the Launcher and are calculated using the size of the button PICT. Only the top and left fields are necessary. ''Required''
 +
 +
'''Button PICT id''' - This is the resource ID of the PICT for the un-highlighted, or normal state, of the button. ''Required''
 +
 +
'''Button PICT handle''' - This is used at runtime and should not be filled in by the user. ''Reserved''
 +
 +
'''Highlighted button PICT id''' - This is the resource ID of the PICT for the highlighted state of the button. This PICT, if specified, is displayed whenever the mouse is determined to be within the button rectangle. ''Optional''
 +
 +
'''Highlighted button PICT handle''' - This is used at runtime and should not be filled in by the user. ''Reserved''
 +
 +
'''Button pressed PICT id''' - This is the resource ID of the PICT for the pressed state of the button. This PICT is displayed when the mouse button is pressed and is within the button rectangle. ''Optional''
 +
 +
'''Button pressed PICT handle''' - This is used at runtime and should not be filled in by the user. ''Reserved''
 +
 +
'''Mouse within snd id''' - This is the resource ID of the sound ("snd') resource that is played whenever the mouse enters the button rectangle. ''Optional''
 +
 +
'''Mouse within snd handle''' - This is used at runtime and should not be filled in by the user. ''Reserved''
 +
 +
'''Launch object type''' - The value of this field specifies what the ApplePCde should do with the file specified by the "App or doc filename" field when the user presses the mouse button while the mouse is within the button rectangle. ''Required''
 +
 +
* Values for this field are as follows:
 +
** 0 - no action; ignore the "launch object" file
 +
** 1 - launch object is an application file
 +
** 2 - launch object is a document file
 +
 +
'''App or doc filename''' - This field contains the full HFS pathname of an application or document and generally is the action that is performed when the user presses the button. Applications and documents are simply launched.
 +
 +
If this field is left empty, ApplePCde will take no action when the user presses the button. It is crucial that you get this field name correct, any errors in the path name could result in a hang of the OS or a crash.
 +
 +
===Customizing ApplePCde===
 +
This section describes a step-by-step process for creating custom ApplePCde resources.
 +
 +
# Make a copy of the Pippin Launch file so that you do not modify your original. It will be easier to "start over" or begin a new project if you keep an unmodified copy of Pippin Launch on hand.
 +
# Prepare your Pippin Launch art and sound files. This may be done using any tools which can create Macintosh PICT and snd data. Many Macintosh graphics programs can save graphics in PICT file format. However, the ApplePCde requires all data to reside in its "resource fork".
 +
 +
Some programs, such as Adobe Photoshop, permit graphics to be saved directly as a PICT resource file. This can simplify your work. Otherwise, you can create graphics and use the Clipboard to copy and paste them directly into the Pippin Launch resource fork using ResEdit.
 +
 +
Sound resource data can be created using the Macintosh microphone or with A/V sound input capabilities. Most likely, for high quality audio, the microphone will not be used. However, it can be useful to "prototype" your sounds with the microphone using the resulting low quality sound as place holders for your final data.
 +
 +
====Creating Launcher Art====
 +
The first step is to choose your background art. The graphic should be a full screen image (640 x 480 pixels) so as to cover the Pippin TV screen. If you have a fully rendered scene, you may only need to cut rectangles out of the background (like a cookie cutter) in order to form your un-highlighted button art. However, button art can be anything you like, even something totally unrelated to the background.
 +
 +
Once you have chosen your background picture, save it as a PICT resource so that you can import it later using ResEdit. Alternatively, you can open the Pippin Launch file using ResEdit, and paste the PICT directly into the Pippin Launch's resources. If you do not have a graphics program that supports the creation of PICT resources, you will need to import your art this way.
 +
 +
====Assigning PICT Resource IDs====
 +
When you paste a PICT into the Pippin Launch resource file, ResEdit assigns a number, called a resource ID, to the data. This number gives the picture a unique name amongst all PICTs in the file. You should assign a resource ID to each picture to help you recall which picture is which. You might choose to use a certain range of numbers for each of the button pictures so that it is easy for you to know which pictures are related to each other by their ID. For example, you might use the IDs 150, 151, and 152 for a button, its highlighted state, and its pressed state, respectively. You might use 160, 161, and 162 for another button. In this example, it's easy to tell which PICTs are associated with each other, and what each of them is by looking at the resource ID. While this methodology can help you keep things organized, it is not required.
 +
 +
====Button Rectangles====
 +
Whether you decide to use the "cookie cutter" method mentioned earlier for making buttons from a fully rendered scene, or some other method altogether, you will need to gather some precise information about the placement of the button art work. If you are cutting buttons out of a background, you will want to use a graphics program that can tell you the XY position of the rectangular patch you copy from the background. This information must be entered into the button rectangle field of the pbtn resource, each of which is used to store button information. This information must be transcribed exactly or the button will not be drawn in the correct position.
 +
 +
=====Making Highlighted Buttons: An Example=====
 +
Once you have cut out buttons from a background, or other source, you may wish to make a graphic for the button's highlighted state. This will be displayed whenever the user's mouse pointer is within the rectangle of the button. This is a form of "hot highlighting" that can be used to indicate that a button exists in an area of the screen. This art is optional. If it is not present, the button will not appear different when the mouse is "over" it.
 +
 +
One technique for making highlighting button art is to begin with a copy of the original button art. Using Adobe Photoshop, for example, you can form a selection area around the edges of whatever graphic element is prominently considered as the button. Invert the selection, and then use an airbrush tool to make a colored halo around the art. This technique can be used to create the appearance of highlights of arbitrary shape and color.
 +
 +
Similar techniques can be used to make "button pressed" art. Keep in mind, though, that the art for the button, its highlighted state, and its pressed state do not have to be related to each other. In fact, a completely different graphic for each state may be appropriate, depending on the "look" you are trying to create. For example, you might use a person's face as the button, the same face with raised eyebrows for a highlighted state, and the same face with an open eyed, open mouthed expression for the pressed state.
 +
 +
====Using Sound====
 +
Sounds can be used to augment the Launcher's behavior. You can use a "startup sound" that is played when the Launcher first starts, perhaps playing a musical theme or an introduction to your product: "Welcome to XYZZY...". Sounds can also be played whenever a user puts the mouse pointer over a button. This can be useful as a audible prompt to "try pressing me", for example, or as something instructional about what will happen if the button is pressed.
 +
 +
Launcher sounds are loaded into memory, so whatever you decide to use must fit into Pippin's memory. You can economize, for example, by using the same sound for all button presses.
 +
 +
To use a sound, simply "paste" it into the Launcher resource file using ResEdit, and assign the sound's resource ID to one of a button's functions by typing in the sound's resource ID into one of the "snd ID" slots of a button: mouse within, button pressed.
 +
 +
====Launch Object====
 +
A launch object determines what happens when the user presses a given button. There are three possible actions:
 +
 +
* do nothing
 +
* launch an application
 +
* open a document
 +
 +
The action of "do nothing" seems likes it is not very useful. However, you can use these types of buttons to play audible instructions by simply associating the appropriate sound resource with the button press. If the user presses the button, some instructions are played out loud, but no other action is taken.
 +
 +
The next two actions, launching an application and opening a document, are self-evident as to what they do. You would use launch a document to open authored files, such as [[HyperCard]] stacks. For a stand-alone application, you would simply launch an application. Of course, if there is only one application on your CD, you would probably just want to launch it directly as described in the "Pippin Startup Process" Technical Note and it is not necessarily for you to use PippinFinder or the Pippin Launch mechanism.
 +
 +
====Customizing PCde Code====
 +
While the source code is currently not provided for the ApplePCde resource, it is simple enough for a developer to write his own PCde in C or Pascal (Actually in any language you want as long as it is able to support Pascal calling conventions at its entry point).
 +
 +
====Memory Utilization====
 +
When PippinFinder calls to the existing PCde module, it has created a 2Meg handle in temporary, initialized a heap into it, and set the current zone to that newly allocated memory. Since control is maintained by the code module until a launch selection is made, the heap remains valid till control is passed back to PippinFinder. When PippinFinder regains control, the heap is disposed and the specified FSSpec is launched.
 +
 +
====Use of Temporary Memory====
 +
When launching applications, Macintosh system software creates a heap zone in the "Multifinder heap" based on the "SIZE" resource information (familiar to users as the Finder's "Get Info" information about an application icon). All resource and other memory allocation takes place within that heap zone unless the application software takes explicit steps to manage memory in other ways. Most applications are designed to simply use their own application heap.
 +
 +
Beginning with System 7.0, application programming interfaces for the use of so called "temporary memory" were made public. Temporary memory is simply memory allocated from the Multifinder heap, the same heap used for application heap allocation. As such, programmers were directed to not use temporary memory for extended periods of time because it could cause the Multifinder heap to become fragmented and, thus, prevent applications from launching due to the lack of appropriate contiguous free space.
 +
 +
Since Pippin is intended primarily as an multimedia playback appliance, however, PCde developers are encouraged to use temporary memory if their memory needs exceed the 2Meg heap provided to them. Since PippinFinder does not know about the temporary memory being used by the PCde module, the module must make the effort to release all used memory in this area before returning code to PippinFinder.
 +
 +
==PippinFinder==
 +
The PippinFinder file is only to be used with CDs that have a multiple-application interface. Since most titles developed for Pippin will involve only a single application launched immediately at start-up, the PippinFinder file is not used and therefore should not be placed in the System Folder. Even with multiple application titles, the PippinFinder does not provide the interface for launching the applications within a title CD; the interface is provided by a Pippin Launch file.
 +
 +
==Stopping INIT Icons==
 +
The Pippin OS frequently includes extensions such as QuickTime and Applejack. Extensions almost always draw an icon when loading, which is what produces the row of icons across the bottom of the screen when the system is booting. The Pippin user experience though should not include such computer specific messages. The user probably will not even know what QuickTime is. Therefore, developers should stop the drawing of icons during the boot process for Pippin CDs.
 +
 +
==Creating Pippin CD-ROMs==
 +
All CD-ROM titles to be played on Pippin Power Players must be "Pippinized" in order to successfully run on a Pippin. This technical note describes the hardware, software, and procedures required to make Pippin-ready CD-ROMs though either modification of already released CD-ROM titles, or in initializing a brand new CD-ROM title.
 +
 +
==Flash Access==
 +
The Flash Access chip is a writable FlashROM chip with a 120K maximum capacity located on the Pippin main logic board. Since the Pippin does not have a hard drive to store information, and external storage devices cannot be assumed to always be present, a developer has very limited space to work with. Developers must therefore recognize the storage limitations of the Flash Access chip, and plan their titles accordingly.
 +
 +
==Pippin Authentication==
 +
In order for Pippin CD-ROMs to run on a Pippin Power Player, they must first go through a Pippin authentication process. The authentication process is about applying an Apple-approved RSA signature, in the form of an electronic encrypted key, onto a Pippin CD-ROM.
 +
 +
==Applejack Input Device Driver==
 +
The Applejack input device driver combines the features of a game-player pad and a mouse or trackball in a small handheld device. Generally, Applejack input devices are attached to a Pippin Power Player (a CD-ROM multimedia player device derived from the PowerPC Macintosh).
 +
 +
==Pippin Video==
 +
This document contains PippinVideo.h and myPippinVideo.c. PippinVideo.h is a header file that contains enumerated constants and structures necessary to access functionality unique to the Pippin video architecture. myPippinVideo.c is sample code that illustrates features unique to the Pippin video architecture.
  
 
=External Links=
 
=External Links=

Revision as of 21:57, 30 September 2020

Pippin-Atmark-Console-Set.jpg
Bandia-Pippin-pcb.jpg

Pippin is a set of technologies designed by Apple Computer for Bandai Digital Entertainment Corporation in Japan. Pippin lets you run specially-modified Macintosh CD-ROMs on a low-cost player that plugs into a standard television set. Runs on a PowerPC 603 processor.

Technical Specifications

Hardware

  • 66MHz PowerPC 603 RISC microprocessor
    • Superscaler, three instructions per clock cycle
    • 8KB data and 8KB instruction caches
    • IEEE standard single and double precision Floating Point Unit (FPU)
  • 6MB combined system and video memory, advanced architecture
    • Easy memory expansion cards in 2, 4 and 8MB increments
  • 128K SRAM store/restore backup
  • 4X CD-ROM drive
  • Two high-speed serial ports, one of which is GeoPort ready
  • PCI-compatible expansion slot
  • Two ruggedized ADB inputs
    • Supports up to four simultaneous players over Apple Desktop Bus (ADB)
    • Will support standard ADB keyboards and mice with connector adapters

Video

  • 8-bit and 16-bit video support
  • Dual frame buffers for superior frame-to-frame animation
  • Support for NTSC and PAL composite, S-Video and VGA (640x480) monitors
  • Horizontal and vertical video convolution

Audio

  • Stereo 16-bit 44kHz sampled output
  • Stereo 16-bit 44kHz sampled input
  • Headphone output jack with individual volume control
  • Audio CD player compatibility

Software

  • Runtime environment derived from Mac OS
  • PPC native version of QuickDraw
  • Reduced system memory footprint (computer specific features removed)
  • Disk-resident System Software stamped on CD-ROM with title
  • System boots off of CD-ROM
  • Pippin System Software upgrades released through CD-ROM stamping operations
  • 68k emulator
  • Macintosh Toolbox intact

Pippin Technical Notes

Devonly.gif

Startup Process

History

On all existing Macintosh computers, the boot process remains the same as it has been since the early days of the Macintosh. That startup process is as follows:

  1. After the loading of the Process Manager, the file name stored in the boot blocks as the startup application is launched.
  2. After a standard format of a hard disk or floppy, this value is set to "Finder". So the Finder is launched as the main application.

On the initial Pippin, CD-ROMs developers were taught a simple way of setting up the startup application by modifying the boot blocks on the volume. While this worked as needed, it was a hack and is not an acceptable solution for shipping disks. It required the target application to be in the "blessed" System Folder, or in some cases, people made the root level of the volume the System Folder. This makes the disks very unattractive when the disk is used in a non-Pippin system (due to the need for the startup application to be in the System Folder). It could also cause problems with future Pippins as there would be more "unique" considerations that would need to be handled as the ROM attempts to override what is on the Pippin CD-ROMs.

The New Pippin Way

The basic startup sequence has been modified for Pippin to allow additional flexibility and better aesthetics on non-Pippin Macintoshes. Further, the new startup process does not require any modification of the boot blocks.

At the point where the application stored in the boot blocks is launched, the startup process has been modified for Pippin purposes. If there is a file called "PippinFinder" in the System Folder, then it is launched. PippinFinder should only be used for developers that want to handle multiple applications per CD. For developers wanting to do this, please see the document regarding PippinFinder.

For single application titles, the startup process is simple. Create an alias to the application you want to launch and place it in the Startup Items folder. Also make sure that PippinFinder has been removed from the System Folder. That is all that is needed. The boot process with launch your application on the next launch rather then launching the Finder. And the final disk that is pressed will not contain the real Finder in the System Folder. The file named "Finder" will actually be just another copy of PippinFinder on final shipping CD-ROMs.

Considerations for Developers

Pippin can have a variable amount of memory, but the size resource can only be configured once, so care should be made in setting this resource.

Pippin has been designed to use as little memory as possible. QuickTime that ships with all Macintoshes is much better in its memory allocation, using very little memory until QuickTime functionality is actually needed. The reason the memory allocation setting is important will become clear. If you have your preferred memory size set to a size which will use up all available application memory space then it means the system heap is unable to grow larger then it is after the startup process.

A better way of writing your application would be to utilize temporary memory more effectively. Make you application work well within a reasonable partition (2 MB) then utilize temporary memory as available. This would allow you application to work well on any memory configuration of Pippin. Will also allow the application to work more flexible on the entire Macintosh family as well.

If you application is configured to use all available memory, then any system extensions or managers that require system heap memory space will not function fully and in some cases not at all. To make sure you run well on all Pippins, you should do all your testing on the base model Pippin with no expanded memory.

Launch Process Override for Developer Enabler

For developers, there is an override in the developer Enabler that allows them to override the above described boot process and go directly to the Finder. While booting, and before the extension loading has completed, hold down the "P" and "L" keys. This will allow the Pippin boot process to fall through and the boot to continue onto the Finder. If you have an alias in the Startup Items folder, the Finder will still attempt to launch the title in the Startup Items folder. This method will not work on shipping systems since the Finder on those machines is not a real Finder, but is another copy of PippinFinder.

Pippin Standard File

Introduction

When developing titles for the Pippin Power Player, many assumptions about storage that are typically made in the Macintosh environment must be slightly altered. Unlike a Macintosh, Pippin does not have a hard disk and the only guaranteed storage media available is 128k of internal NVRAM (non-volatile random access memory). An optional floppy disk drive could be installed as well, but this should not be assumed. Of the 128k built-in NVRAM, 8k is used by the system software, leaving 120k for general purpose storage. Obviously, assumptions made about file storage while working with virtually unlimited hard disk space are very different than working with a limited and relatively small amount of storage.

The following sections offer specific considerations for developers to keep in focus while developing new titles so they will be able to work effectively within Pippin storage limitations. In general, however, developers should build their titles with the intention of eliminating unnecessary storage, or saved data. With such a small amount of storage, utilizing available NVRAM as efficiently as possible is critical.

Non-Volatile RAM (NVRAM)

The internal NVRAM is represented as a small HFS (Hierarchical File System) volume. By small HFS, this means that only two levels of hierarchy is allowed: the first level being the root level, the second level being folders appearing at the root level. In fact, within Pippin's NVRAM, folders can only appear at the root level, and no other folders are allowed within those folders. Nonetheless, despite this limited hierarchy, all normal file manager calls will treat NVRAM as a normal HFS disk.

Single Folder Per Title

In order to reduce confusion, it is strongly recommended that developers save all files, preferences, and any other data in a single folder at the root level of either the NVRAM or a floppy disk. This folder would have a name closely related to the title name, and a name that would be included as a string resource. The title-named folder will provide organization for the user, and further simplify tasks such as copying, moving, and deleting files that are associated with particular a title.

Preference Files

On the Macintosh, Preferences files are stored in the System Folder of the start-up disk. Since Pippin boots from a CD-ROM, dynamic Preferences files cannot be stored there. Therefore, if a title needs a writable Preferences file, it is suggested that the Preferences file also be stored in the title-named folder (see section 3). By ensuring that the Preferences file is of type "pref':" it does not also need to be displayed to the user.

Pippin Standard File

Since the target audience for Pippin is not always computer users, the Macintosh Standard File is unnecessarily complex. New system software that simplifies the Standard File interface is provided on Pippin. Still, the new calls in the Pippin Standard File behave in a similar fashion to the Macintosh Standard File, and the main differences between the two is that the Pippin Standard File has larger colored icons, no "New Folder" button, and no "Desktop Button."

There are several new Pippin Standard file functions described in Pippin.h. PippinStandardGetFile, PippinStandardPutFile and PippinStandardDeleteFile are the three main functions:

pascal void PippinStandardGetFile(FileFilterProcPtr filefilter
	short numTypes,
	SFTypeList typeList,
	StandardFileReply *reply);

pascal void PippinStandardPutFile(ConstStr255Param prompt
	ConstStr255Param defaultName,
	StandardFileReply *reply);
pascal OsErr PippinStandardDeleteFile(long *bytesRequested);

PippinStandardGetFile and PippinStandardPutFile in the Pippin Standard File work the same as StandardGetFile and StandardPutFile in the Macintosh Standard File. PippinStandardDeleteFile, however, is a new call in the Pippin Standard File which was created so files may be deleted while a title is running. This call does not allow copying or moving of files though. These tasks should be accomplished with the Pippin Navigation CD, which is included with each shipped Pippin unit.

The Pippin Standard File calls the title-named folder that is also specified in the "pipn" resource.

Pippin Launch

Introduction

The PippinFinder Technical Note describes the "replacement" Finder file for the Pippin System Folder, and that the actual code that drives a multiple application-interface is inside the Pippin Launch file. Apple provides an initial interface, a simple button interface, with the buttons changing appearance when they are selected. In summary, Pippin Launch is the file that PippinFinder uses, and this document is describing the "PCde" resource that Apple provides for developers to use. If you wish functionality beyond what PCde code implements, you will need to write your own code module. (See the "PippinFinder" Technical Note for details on how to create your own code module.)

Note: If you have a single-title CD and do not want to use a multiple-application interface via PippinFinder, you must ensure that the Pippin Launch file is removed from your System Folder on your Pippin CD. If not removed, you could cause problems with the boot process. The PCde module allows developers to easily customize the visual appearance of the Pippin startup environment when a Pippin CD is booted. The PCde module will only use the 2Meg provided to it via the PippinFinder. This is not of concern since it will all be disposed of before the title is launched.

To distinguish between the Apple provided PCDe module, and potential PCDe modules that may be created by developers, throughout the rest of this document, the Apple provided PCDe will be referenced as "ApplePCDe".

PCde Interface Philosophy

The Launcher presents the user with a single window that contains a background picture and an arbitrary number of buttons.

The background can be a PICT of any size, although it is recommended that the PICT be 640 x 480 pixels in size so it will completely fill Pippin's screen, much like the Macintosh "desktop". If the PICT is not big enough to fill the entire screen, the remaining area will be filled with the black.

Each button is a rectangular PICT of any size. There are as many as three PICT resources associated with each button:

  • one for the button that is un-highlighted
  • one for the button that is highlighted (used when the mouse is within the button rectangle if the resource is present)
  • one for the button that is in a "pressed" state (used when the user presses the mouse button when the mouse is within the button rectangle).

Each of these buttons should be the same pixel dimensions. Each, when present, are displayed at the coordinates of the button which are specified separately.

The behavior of the window is that, whenever the mouse is found to be within any of the buttons, the button's "highlighted" graphic is displayed (if it exists). If a "mouse within" sound exists, it is played as soon as the mouse is detected within the button rectangle. If the mouse leaves the highlighted button, the button's un-highlighted button graphic is again displayed. No mouse actions other than positioning movement is required by the user to get either graphical and audible feedback.

Launcher Resource Overview

The resource fork of the Pippin Launch file contains all the data used by the ApplePCde. This includes all graphics and sound data, as well as small descriptive resources which tell the Launcher where to display buttons, how to highlight them, what sounds to play, etc. These resources can be edited with the resource editor ResEdit 2.1.3 (or higher) utility to create a custom launching environment for Pippin CDs.

There are only two types of resources that need to be created:

  • a single "background" resource (i.e., pbkg)
  • some number of "button" resources (i.e., pbtn)

The following sections describe these resource types in more detail. Included in the resource fork of the Pippin Launch file on the Pippin Developer SDK CD are ResEdit "template" resources which simplify the creation of the background and button resources.

The Background Resource

The background resource, pbkg, tells the Launcher which PICT resource are to be the background picture for the launcher's window. It also tells the Launcher which sound, snd, should be played when the Launcher first starts up. Only one pbkg resource should be present in the Launcher resource fork.

The contents of the pbkg resource are as follows:

Background PICT id - This is the resource ID of a PICT resource that is the background picture for the Launcher window. The dimensions of the PICT are used to set the size of the Launcher window.

Background PICT handle - This is used at runtime to hold a handle to the background picture and should not be filled in by the user. Reserved

Startup snd id - This is the resource ID of a snd resource. The sound, if specified, is played when the launcher starts up and can be used to play introductory music or instructions. Set this to zero if you don't want to use a startup sound.

Button Resources

There can be any number of button resources present (i.e., any number of the resource pbtn). Each describes where a button is placed in the window, whether it is a hot highlighted or un-highlighted graphic, whether it is a "pressed" graphic, and what sounds should be played for the "mouse entering the button" and "mouse pressing the button" events.

The contents of the pbtn resource are as follows:

Button rectangle - This is used to specify the top left coordinates of the position of all button art for the button. The bottom and right members of the rectangle are ignored by the Launcher and are calculated using the size of the button PICT. Only the top and left fields are necessary. Required

Button PICT id - This is the resource ID of the PICT for the un-highlighted, or normal state, of the button. Required

Button PICT handle - This is used at runtime and should not be filled in by the user. Reserved

Highlighted button PICT id - This is the resource ID of the PICT for the highlighted state of the button. This PICT, if specified, is displayed whenever the mouse is determined to be within the button rectangle. Optional

Highlighted button PICT handle - This is used at runtime and should not be filled in by the user. Reserved

Button pressed PICT id - This is the resource ID of the PICT for the pressed state of the button. This PICT is displayed when the mouse button is pressed and is within the button rectangle. Optional

Button pressed PICT handle - This is used at runtime and should not be filled in by the user. Reserved

Mouse within snd id - This is the resource ID of the sound ("snd') resource that is played whenever the mouse enters the button rectangle. Optional

Mouse within snd handle - This is used at runtime and should not be filled in by the user. Reserved

Launch object type - The value of this field specifies what the ApplePCde should do with the file specified by the "App or doc filename" field when the user presses the mouse button while the mouse is within the button rectangle. Required

  • Values for this field are as follows:
    • 0 - no action; ignore the "launch object" file
    • 1 - launch object is an application file
    • 2 - launch object is a document file

App or doc filename - This field contains the full HFS pathname of an application or document and generally is the action that is performed when the user presses the button. Applications and documents are simply launched.

If this field is left empty, ApplePCde will take no action when the user presses the button. It is crucial that you get this field name correct, any errors in the path name could result in a hang of the OS or a crash.

Customizing ApplePCde

This section describes a step-by-step process for creating custom ApplePCde resources.

  1. Make a copy of the Pippin Launch file so that you do not modify your original. It will be easier to "start over" or begin a new project if you keep an unmodified copy of Pippin Launch on hand.
  2. Prepare your Pippin Launch art and sound files. This may be done using any tools which can create Macintosh PICT and snd data. Many Macintosh graphics programs can save graphics in PICT file format. However, the ApplePCde requires all data to reside in its "resource fork".

Some programs, such as Adobe Photoshop, permit graphics to be saved directly as a PICT resource file. This can simplify your work. Otherwise, you can create graphics and use the Clipboard to copy and paste them directly into the Pippin Launch resource fork using ResEdit.

Sound resource data can be created using the Macintosh microphone or with A/V sound input capabilities. Most likely, for high quality audio, the microphone will not be used. However, it can be useful to "prototype" your sounds with the microphone using the resulting low quality sound as place holders for your final data.

Creating Launcher Art

The first step is to choose your background art. The graphic should be a full screen image (640 x 480 pixels) so as to cover the Pippin TV screen. If you have a fully rendered scene, you may only need to cut rectangles out of the background (like a cookie cutter) in order to form your un-highlighted button art. However, button art can be anything you like, even something totally unrelated to the background.

Once you have chosen your background picture, save it as a PICT resource so that you can import it later using ResEdit. Alternatively, you can open the Pippin Launch file using ResEdit, and paste the PICT directly into the Pippin Launch's resources. If you do not have a graphics program that supports the creation of PICT resources, you will need to import your art this way.

Assigning PICT Resource IDs

When you paste a PICT into the Pippin Launch resource file, ResEdit assigns a number, called a resource ID, to the data. This number gives the picture a unique name amongst all PICTs in the file. You should assign a resource ID to each picture to help you recall which picture is which. You might choose to use a certain range of numbers for each of the button pictures so that it is easy for you to know which pictures are related to each other by their ID. For example, you might use the IDs 150, 151, and 152 for a button, its highlighted state, and its pressed state, respectively. You might use 160, 161, and 162 for another button. In this example, it's easy to tell which PICTs are associated with each other, and what each of them is by looking at the resource ID. While this methodology can help you keep things organized, it is not required.

Button Rectangles

Whether you decide to use the "cookie cutter" method mentioned earlier for making buttons from a fully rendered scene, or some other method altogether, you will need to gather some precise information about the placement of the button art work. If you are cutting buttons out of a background, you will want to use a graphics program that can tell you the XY position of the rectangular patch you copy from the background. This information must be entered into the button rectangle field of the pbtn resource, each of which is used to store button information. This information must be transcribed exactly or the button will not be drawn in the correct position.

Making Highlighted Buttons: An Example

Once you have cut out buttons from a background, or other source, you may wish to make a graphic for the button's highlighted state. This will be displayed whenever the user's mouse pointer is within the rectangle of the button. This is a form of "hot highlighting" that can be used to indicate that a button exists in an area of the screen. This art is optional. If it is not present, the button will not appear different when the mouse is "over" it.

One technique for making highlighting button art is to begin with a copy of the original button art. Using Adobe Photoshop, for example, you can form a selection area around the edges of whatever graphic element is prominently considered as the button. Invert the selection, and then use an airbrush tool to make a colored halo around the art. This technique can be used to create the appearance of highlights of arbitrary shape and color.

Similar techniques can be used to make "button pressed" art. Keep in mind, though, that the art for the button, its highlighted state, and its pressed state do not have to be related to each other. In fact, a completely different graphic for each state may be appropriate, depending on the "look" you are trying to create. For example, you might use a person's face as the button, the same face with raised eyebrows for a highlighted state, and the same face with an open eyed, open mouthed expression for the pressed state.

Using Sound

Sounds can be used to augment the Launcher's behavior. You can use a "startup sound" that is played when the Launcher first starts, perhaps playing a musical theme or an introduction to your product: "Welcome to XYZZY...". Sounds can also be played whenever a user puts the mouse pointer over a button. This can be useful as a audible prompt to "try pressing me", for example, or as something instructional about what will happen if the button is pressed.

Launcher sounds are loaded into memory, so whatever you decide to use must fit into Pippin's memory. You can economize, for example, by using the same sound for all button presses.

To use a sound, simply "paste" it into the Launcher resource file using ResEdit, and assign the sound's resource ID to one of a button's functions by typing in the sound's resource ID into one of the "snd ID" slots of a button: mouse within, button pressed.

Launch Object

A launch object determines what happens when the user presses a given button. There are three possible actions:

  • do nothing
  • launch an application
  • open a document

The action of "do nothing" seems likes it is not very useful. However, you can use these types of buttons to play audible instructions by simply associating the appropriate sound resource with the button press. If the user presses the button, some instructions are played out loud, but no other action is taken.

The next two actions, launching an application and opening a document, are self-evident as to what they do. You would use launch a document to open authored files, such as HyperCard stacks. For a stand-alone application, you would simply launch an application. Of course, if there is only one application on your CD, you would probably just want to launch it directly as described in the "Pippin Startup Process" Technical Note and it is not necessarily for you to use PippinFinder or the Pippin Launch mechanism.

Customizing PCde Code

While the source code is currently not provided for the ApplePCde resource, it is simple enough for a developer to write his own PCde in C or Pascal (Actually in any language you want as long as it is able to support Pascal calling conventions at its entry point).

Memory Utilization

When PippinFinder calls to the existing PCde module, it has created a 2Meg handle in temporary, initialized a heap into it, and set the current zone to that newly allocated memory. Since control is maintained by the code module until a launch selection is made, the heap remains valid till control is passed back to PippinFinder. When PippinFinder regains control, the heap is disposed and the specified FSSpec is launched.

Use of Temporary Memory

When launching applications, Macintosh system software creates a heap zone in the "Multifinder heap" based on the "SIZE" resource information (familiar to users as the Finder's "Get Info" information about an application icon). All resource and other memory allocation takes place within that heap zone unless the application software takes explicit steps to manage memory in other ways. Most applications are designed to simply use their own application heap.

Beginning with System 7.0, application programming interfaces for the use of so called "temporary memory" were made public. Temporary memory is simply memory allocated from the Multifinder heap, the same heap used for application heap allocation. As such, programmers were directed to not use temporary memory for extended periods of time because it could cause the Multifinder heap to become fragmented and, thus, prevent applications from launching due to the lack of appropriate contiguous free space.

Since Pippin is intended primarily as an multimedia playback appliance, however, PCde developers are encouraged to use temporary memory if their memory needs exceed the 2Meg heap provided to them. Since PippinFinder does not know about the temporary memory being used by the PCde module, the module must make the effort to release all used memory in this area before returning code to PippinFinder.

PippinFinder

The PippinFinder file is only to be used with CDs that have a multiple-application interface. Since most titles developed for Pippin will involve only a single application launched immediately at start-up, the PippinFinder file is not used and therefore should not be placed in the System Folder. Even with multiple application titles, the PippinFinder does not provide the interface for launching the applications within a title CD; the interface is provided by a Pippin Launch file.

Stopping INIT Icons

The Pippin OS frequently includes extensions such as QuickTime and Applejack. Extensions almost always draw an icon when loading, which is what produces the row of icons across the bottom of the screen when the system is booting. The Pippin user experience though should not include such computer specific messages. The user probably will not even know what QuickTime is. Therefore, developers should stop the drawing of icons during the boot process for Pippin CDs.

Creating Pippin CD-ROMs

All CD-ROM titles to be played on Pippin Power Players must be "Pippinized" in order to successfully run on a Pippin. This technical note describes the hardware, software, and procedures required to make Pippin-ready CD-ROMs though either modification of already released CD-ROM titles, or in initializing a brand new CD-ROM title.

Flash Access

The Flash Access chip is a writable FlashROM chip with a 120K maximum capacity located on the Pippin main logic board. Since the Pippin does not have a hard drive to store information, and external storage devices cannot be assumed to always be present, a developer has very limited space to work with. Developers must therefore recognize the storage limitations of the Flash Access chip, and plan their titles accordingly.

Pippin Authentication

In order for Pippin CD-ROMs to run on a Pippin Power Player, they must first go through a Pippin authentication process. The authentication process is about applying an Apple-approved RSA signature, in the form of an electronic encrypted key, onto a Pippin CD-ROM.

Applejack Input Device Driver

The Applejack input device driver combines the features of a game-player pad and a mouse or trackball in a small handheld device. Generally, Applejack input devices are attached to a Pippin Power Player (a CD-ROM multimedia player device derived from the PowerPC Macintosh).

Pippin Video

This document contains PippinVideo.h and myPippinVideo.c. PippinVideo.h is a header file that contains enumerated constants and structures necessary to access functionality unique to the Pippin video architecture. myPippinVideo.c is sample code that illustrates features unique to the Pippin video architecture.

External Links

See Also