Cross Platform Development (V1, 3-22-01) Marc Lee Multimedia MLMultimedia@cs.com
Cross Platform Development for Authorware 5.x
Marc Lee
www.MLMultimedia.com
Version 2.0, April 2, 2001
TABLE OF CONTENTS
Introduction
The Mac Environment
Fonts
Native Authorware Tools in Cross-Platform Projects
Differences in Standard Plugins
Cross-Platform Use of Media
Pathnames
Specialized Plugins and Xtras
Packaging Your File
Special Topics
Creating a Cross Platform CD
Finding the Name of the Mac Hard Drive
Creator Types on the Mac
Introduction
This paper is intended for Authorware developers who are responsible for providing a version of their project for both Mac and Windows. Obviously, there are many possible specifics that I have not covered. There is potentially no limit to the list of differences between the PC and the Mac versions of Authorware pieces, as every function or media type no matter how obscure might work differently when ported to the Mac.
Nevertheless, this paper covers all the basics of porting a project from the PC to the Mac. In the last year I have been involved in porting three pieces from the PC to the Mac. I put into this paper everything I wish someone had told me before I started, but in fact had to discover on my own, usually after having spent hours, if not days, of frustration not knowing what detail I had overlooked. So here’s hoping that the contents herein will save you some of the frustration and wasted time that these issues caused me.
This paper assumes that you are working in AW1 5.0 or later. Therefore, all actual development is done on the PC (there being no Mac development environment for 5.0 or later) and ported to the Mac. I assumed for this paper that you are unfamiliar with the Mac, but understand Windows to some degree. I’ve put a lot of Mac basics into this, but only what I had to learn to manage these PC-to-Mac AW porting projects. The only Mac environment I am familiar with is the PPC (PowerPC) architecture. There are some Mac 68K systems out there, and there is a 68K option when you package for the Mac, but beyond that point, I really do not know if there are special cases that apply to the 68K processor versus the Power PC.
The Mac Environment
After you have completed your piece on the PC (we’ll cover the development phase a little later in this paper), you will transport your piece over to a Mac. You or someone in your project is going to need a Mac to complete this work. If you don’t have one available, make sure the client knows he/she will have to supply you with a PowerPC Mac to perform the porting task. Everything I have done has been with the Mac OS 8.0 or later. I believe everything I have said would apply to Mac OS 7.0 or later, but I haven’t tried things prior to 8.0.
For the Mac, you will save the piece on the PC and package without runtime, creating an A5R file. This is the file that will go to the Mac. Move the file to the Mac in any convenient manner. If you have a CD burner on the PC, you can make a PC CD-ROM. The Mac can read it. When the Mac reads it, it will pop a CD icon onto the Mac desktop. Make sure that the file name of the A5R piece has not been truncated to DOS format. If it has, you can rename the file once you copy it to the Mac hard drive. Also I often use a Zip disk. A PC’s Zip disk can be read on the Mac also (assuming there’s a Zip drive on the Mac).
All your external media files will go to the Mac side also. But we will talk about these separately a bit later.
On the Mac you will need the Mac Player and the Mac Packager. To download these two files and the rest of the Mac environment, go to the Macromedia site and type ‘Authorware Mac Player’ into the Search tool. You will get a link to for Authorware 5.1 Mac Player, but actually it links you to the download site for the 5.2 Player and Packager. In addition when you get this download you will get the whole Mac environment, including the Xtras, drivers, and documentation. I recommend that you try to get the download using a Mac with a relatively fast network connection. The download is several MB and can take upwards of an hour on a slow dialup line. Once the download hits the Mac, it will self-extract and create the Authorware folder and file structure you need.
If your piece is basic with no external media, completely contained in a single file, you would create a folder on your Mac desktop for the project. Then you would copy the A5R file from the Zip or CD to this folder. Then, from your newly-created Mac folder, drag the Mac Player, the Xtras folder, and the MacromediaRuntimeLib file from the Mac environment to your project folder. To run your piece, you click on the Mac Player. From the dialog, select the A5R file you want to run (the one you just dragged to the project folder) and open. The piece will open and run as normal. Later, we’ll cover the Mac Packager, which encapsulates the player and the A5R in one file -- the equivalent of a Windows exe file for the Mac.
Fonts
As you run your piece on the Mac for the first time, do not be surprised – leaving all external media out of the discussion for the time being – if the text appears distorted, out of position, or in the wrong size as compared to how it looked on the PC. Fonts are the single biggest headache in porting to the Mac. Even if you stick to the rule of using only standard PC fonts (Arial, Times New Roman), you will find that the Mac positions the characters higher in the text ‘bounding box’ than the PC, making the text appear out of position if you are attempting to line it up with a graphic or another item in your content. For example, often the lesson title and the panel number within the lesson go into little graphic panels in your piece’s UI that set the text off. On the Mac the text may not be positioned in the graphic as you expect. Ultimately, there is no total solution for this. The only defense is to allow for a 3-4 pixel difference in positioning when designing the cross-platform UI graphics.
Fontmap.txt2
In the case where you want to use some specialized font, you can use the fontmap.txt file that is in the Authorware folder on your PC. This file can map the font to use on the Mac, given the font on the PC. Fontmap.txt can also map different point sizes on the Mac for a given point size on the PC. For some specialized fonts, I have found that you’ll need four point sizes higher on the Mac than on the PC. I have found this to be the case for the following fonts:
Native Authorware Tools in Cross-Platform Projects
To a significant degree, other than fonts, you can count on code written on the PC side to work exactly as expected on the Mac side. For example, scripting: all System Functions and Variables operate just like on the PC side3; at least I’ve never seen any differences. All of the Palette icons – Display, Motion, Interaction, Pause, Erase, etc. – work just the same. You have no real worries of this kind in porting.
Display Icon
Now that I’ve made this sweeping generalization, I must note one major exception to it. The Display Icon’s Mode and Fill inspectors operate a little differently on the Mac. The difference is subtle, but the result may not be. Graphics done inexactly on the PC may look perfectly OK on the PC, but will appear transparent on the Mac. This can be startling if you don’t expect it and don’t realize what’s happening.
Here’s what’s happening if you get that ‘transparent’ effect on the Mac: On the PC you can get an opaque effect even if the Mode inspector is set to transparent, IF the fill inspector is set to a fill option. Make sure, for cross platform, you haven’t carelessly selected ‘transparent’ and depended on the fill to create the opaque effect. It won’t, on the Mac, even though it will on the PC.
Differences in Standard Plugins
The next concentric circle of functionality beyond the internal AW tools are the Xtras and UCDs/DLLs that ship with the product and show up in your AW folder when you install AW. A good number of these are Windows specific. For example, all U32 files such as FTP.u32, ODBC.u32, and so on may not be usable on the Mac side unless there is the corresponding XMCD in the Mac environment. And certainly things that are Windows-specific such as WinCtls.u32 and WinApi.u32 will not be usable. I personally have used no UCDs at all when I am doing cross platform. As far as my experience goes, the same limitations are not true among the standard Xtras. For each of the standard, out-of-the-box Xtras that ship with AW, the PC and the Mac are identical. For whatever Xtras you ship with your piece, you will ship the same or the corresponding Xtra for the Mac. Often, we use an Xtra without knowing it. For instance any time you use a non-native transition, you are loading it from an Xtra. Since you must actively load a UCD function when you want it, there is little chance that you would inadvertently call a UCD function without knowing it. If you do use a UCD function, make sure you can load the corresponding XMCD on the Mac side and that its version of the function operates the same.
Cross-Platform Use of Media
Any media that you include with your piece, whether loaded internally or externally, must at the fundamental level be cross-platform compatible. Fortunately, most media formats that work on the PC work on the Mac as well.
External Text
If you are reading text into your piece from external files, the same text files that operate on the PC; using the ‘.txt’ extension will work on the Mac. To call the file on the Mac you need make no adjustment in your code. The ReadExtFile(FileLocation^“myfile.txt”) command will work in both. The only caveat is the file name distortion that can occur at times moving from a PC CD-ROM to a Mac. The ISO file names may not be preserved on the Mac. To combat this potential problem do one of the following: 1) transfer your files to the Mac via Zip, or 2) Use short file names for your text files, 3) when your files are copied to the Mac HD, edit the names to restore the original spelling.
Graphics
The most popular graphics formats used with AW – BMP, GIF, JPG, TIF, PNG, PSD – will work without any alteration on the Mac. Alpha channel-compliant files such as TIF, PNG, and PSD – retain their alpha channel capabilities on the Mac. One question I cannot answer is – is there a difference in the compression done on the Mac? That is, will the BMPs be as small on the Mac as on the PC. I do not know the answer to that. However, basically, you should have no problems in porting your internal or external graphics. Again, any display icon can cause unexpected transparency (as discussed above) if the mode inspector is set to Transparent.
Audio
The same is true for your audio files. I have only used WAV files. I have experienced no problems in porting them to the Mac. I know of no reason why AIF, SWA or VOX files would cause problems on the Mac. Note: the VOX format requires a DLL (VTC32161.dll). You’ll have to check to see if there is support on the Mac side.
Movie Files
Movies can cause problems, in that the only truly cross-platform format is QuickTime. Using QuickTime, I have experienced problems, but in general the problems have more often been on the PC. QuickTime is an Apple Computer product.
The goal here is to use the same MOV (QuickTime) files to play your piece on the PC and the Mac. This is definitely possible. Please note that in this discussion I am assuming that you will be using QuickTime 4, which is the latest version from Apple. On your development PC, you will need to have a copy of the QuickTime Player if you don’t already have it. The player is freeware and is available from the Apple site.
To play QuickTime movies, the users’ machine also needs to have the QuickTime player. For Mac, again, it’s simpler than the PC. All Macs past Mac OS 7.0 automatically have the QT player when shipped from the factory. So on this, you only have to worry about the PC side. You can provide a QuickTime installer with your piece and test for QuickTime using BudApi (more about BudApi, later). There is also a check-for-QT ActiveX control. For information on this see www.apple.com/quicktime. Of course, this would only apply to the PC side, so you’d have to branch around it for your Mac-side code. You wouldn’t need it anyway, since you’re assured of having QT on the Mac.
For QuickTime movies you will have to use the QTAsset Sprite (for anything past QuickTime 2). You’ll have to make sure to distribute the QTAsset.x32 xtra with your piece. You will NOT need the QT movie driver (A5qt32.xmo) once you are past QuickTime version 2. To use the sprite, you’ll need the QT Asset Help. This is in your AW folder, in Xtras, in the QuickTime Asset folder. There, you will find the complete reference to scripting in AW for the QT Asset Sprite.
Troubleshooting QuickTime in AW
Here are some hints related to specific problems:
Problem: The sound is not playing on my QT movie
Solution: Note if an audio file plays just before the movie. It may be that the audio channel is not clear. Use the unload() function to clear the audio (unload(@”LastAudioIcon”). Also, you can place a .1 second pause in the flowline after the audio icon to give AW time to unload and release the audio driver. In the case where the user might interrupt an audio file (say, the narrator) to click to play a movie, you might consider creating a ‘null’ audio file (you’ll need to use the sound recorder that ships with Windows or some other sound recording software such as SoundForge). This should be a quarter second of ‘dead air.’ Place this dead air sound file just above the QT Sprite in the flowline to clear the audio channel to be ready for the MOV’s audio.
Problem: The movie is not playing
Solution: Install QuickTime if you do not have it. If you do, click on the movie file outside of AW. The QuickTime player will popup. If the movie does not play in the player, this means that there is some problem with the movie file itself. Often this is the result of the movie having been compressed in a codec that you do not have on your machine.4 Check with the person who created the MOV file. The most generally used QuickTime codec today is Sorenson. If the movie does play in the player outside of AW, most likely you have a pathing problem where the sprite is not able to find the movie file. There is more about construction of paths for cross platform development later in this paper.
Printing In Cross Platform Settings
Often developers are asked to have certain documents printable from the AW piece. This may include printing course certificates or reference documents related to the CBT content. The best format to distribute any document for cross-platform use is Acrobat. Using Acrobat means that one copy of the document (a PDF file) will be usable on both the Mac and PC. Of course, you will have to assure that the user’s machine has the Acrobat Reader on it. The Reader is freeware from Adobe. Most users will have it, but if not it is easy to get a copy from the Adobe website. It is possible to distribute the Acrobat reader installer with your piece, thereby enabling your user to install Acrobat from the materials on your CD-ROM if you desire. Even more user-friendly would be to test for Acrobat on the user’s system and, if not found, offer to launch the Acrobat installer in your own code. If you know the user will have a web connection when running your piece you can simply use GoToNetPage to the download page of the Adobe website and have the user download a copy of the installer themselves.
Once there is a copy of Acrobat Reader on the user’s machine, you can use JumpPrintReturn in a calc icon to print the Acrobat document. This will work for both platforms. Another alternative, which I have recently adopted, is using the PDFXtra from Integration New Media (www.integration.qc.ca). This encapsulates all the functions of Acrobat and the Reader in a single API that is accessible with AW scripting calls. This Xtra is available in both Mac and PC versions. This tool can enable you to print the document without actually having it pop up on the screen, which calling Acrobat from JumpPrintReturn would do.
If you are using the PDFXtra, note that, for the Mac, you may only include one PDF Xtra Asset Sprite in your piece. This is noted on the INM website. For each document you want to use you have to re-program the sprite with AW scripting to open that document. Contact me by mail (see the running header) if you have trouble understanding this.
Pathnames
One of the biggest headaches in cross-platform is the creation of working pathnames for your assets. Most AW pieces today use some external media, whether it is movies, graphics, audio, or text. If you are using QuickTime movies (and if later than QT2.12), then certainly at least they will be external, since there is no internal movie file capability with the QT Asset. The first thing to decide is – how will your piece be distributed? If it’s for the Internet, we’ll cover that aspect later. If it’s CD-ROM, then you have a couple of decisions to make. A typical method of distributing for CD-ROM is to create the AW piece with all media externalized. This keeps the file size of the packaged piece relatively small. Many developers then create a separate installation executable (often in AW) where the packaged piece gets copied to the end user’s hard drive and this piece looks out to the CD-ROM for the media files. This is where your pathing logic is going to be critical: The AW piece on the HD has to find the assets on the CD-ROM drive. Other developers simply leave the packaged piece and the assets on the CD and have the end user run off the CD. The former method is superior in that the piece will run far better if the packaged file is on the hard drive. It will cause a few more pathing challenges, but it will work.
If you move your packaged executable file to the hard drive, keeping the assets on the CD, then you will have to create a path in your AW code based on the CD drive. Typically the AW piece will need a script to create a path to the asset looking something like this:
MediaPath := “E:\\Graphics\\Graphics01.bmp”
Where MediaPath is the AW custom variable, ‘E:’ is the name of the CD drive on the end user’s machine, “\\” is the file delimiter (escape character and the file delimiter). There are two things you’ll have to adapt in this for the Mac (and one thing for the PC).
First, we can’t assume that the ‘E:’ drive is always going to be the CD drive on every PC. Yet we’ll need to know this fact at runtime if we expect to be able to look to the CD to pick up our external media. A solution for this is to write the name of the CD drive into a text file as part of your installation or setup piece that copies the packaged file to the user’s hard drive. As part of this code, place a script that parses the AW system variable, FileLocation, getting the first character. Since this is part of the install code executing off the CD, on the PC that character will always be the CD drive. Then write this character to a text file and copy that file to the root location on the hard drive where you’re going to copy your AW packaged file. Then the packaged file can read the drive letter in question off that text file and always prepend it to all path names when looking for assets on the CD.5
For the Mac, all of this thinking will be thrown out. The Mac has drive ‘names’ rather than letters identifying the different drives on the system. So this means that the CD drive has a name. Luckily, the name is whatever name you give your CD when you burn it. So in building pathnames for the Mac, you’ll always prepend the (hardcoded) name of the CD that you’ll use. Let’s pretend that you’ll name the CD-ROM for your project, MYCBT. Then the first portion of the pathname will be ‘MYCBT’ on the Mac side. There’s only one other detail that affects us on the Mac side, the file delimiter. Just as we have ‘//’ between folders and files on the PC we have ‘:’ - the colon – on the Mac.
So now let’s build our script for the pathname in a cross-platform manner, taking into account the issues described above.
--get the CD drive
If Machine = 3 then CDDrive := ReadExtFile(FileLocation ^ “FileWithCDLetter.txt”)^”:”
Else CDDrive := “MYCBT” -–note that we hard coded it for the Mac
End if
--Create the file delimiter for each platform
Test(Machine = 3, FileDelimiter := “\\” , FileDelimiter := “:”)
--Create the path
MediaPath := CDDrive ^ FileDelimiter ^ “Graphics” ^ FileDelimiter ^ “Graphics01.bmp”
(Note the use of the Machine variable which returns 3 for a PC and 5 for a PowerPC. Note also the additional colon is added to the path on the PC. This comes after the drive name and before the first file delimiter: ‘E:’)
So here is what you will have on the different machines:
Mac MediaPath: MYCBT:Graphics:Graphics01.bmp
PC MediaPath: E:\\Graphics\\Graphics01.bmp
If you will run everything straight off the CD, then the pathing problems will be a little easier. All the paths to the media can start with FileLocation. Only the file delimiters will vary. Here is the same script for the execute-off-the-CD route.
--delimiter
Test(Machine = 3, FileDelimiter := “\\” , FileDelimiter := “:”)
--path
MediaPath := FileLocation ^ “Graphics” ^ FileDelimiter ^ “Graphics01.bmp”
Note the FileLocation includes the trailing file delimiter so you don’t need one before “Graphics.”
Use Subroutines to Call Assets
To the extent that you can, I recommend the use of subroutines to call your external media assets. For example, instead of placing QT Asset Sprites throughout your piece, use a single subroutine for all the movies in your piece. This way, if you are forced to change your paths between authoring mode and packaged mode (or if you have to debug), you will only have to do it in one place.
Specialized Plugins and Xtras
Third party Xtras are often used with AW; there are dozens out there, everything from database plugins to special visual transitions, and so forth. My own experience is with the PDF Xtra (see the section on ‘Printing in Cross Platform Settings,’ above) and the BudApi Xtra.
When using any Xtra in authoring, first, be sure that there is a corresponding Xtra for the Mac side. Most third parties do provide a version of their Xtras for both platforms, but even if they do, they may not support every function on both platforms. The key here is to check the Xtra developer’s web site or documentation; there, usually, is a cross-platform compatibility chart, which will indicate, function by function, whether it’s available on both platforms. Be sure you compensate in your code for functions that are single platform only, or better yet, don’t use any such single-platform-only functions.
For system functions such as creating folders, moving files, and many dozens of other things, I highly recommend using BudApi (www.mods.com.au for a download). This plug in comes in both an Xtra and in a UCD. Be very sure you use only the Xtra in authoring mode. If you happen to load functions from the UCD, they will not work on the Mac side. Of course, you must also get the Xtra from the BudApi website for the Mac. If you’re unfamiliar with BudApi, you should know that once you register the Xtra during authoring, the Mac side’s BudApi Xtra will recognize your registration and will not give you the ‘splash’ screen indicative of non-registration.
Packaging Your File
To operate in a dual platform environment, you’ll most likely package your file twice on the PC, once for Windows and once, without runtime, for the Mac. In this case you’ll have to include two copies of your packaged piece on the CD. We’ll talk in a minute about burning a CD for Mac and PC use. The necessity of two copies of the packaged piece is another reason to externalize the media. Using internal media, at some point, it is going to become burdensome to have two copies of your packaged piece on a 650 MB CD. On the other hand, the likelihood of this causing problems when utilizing externalized media is extremely remote, while it could happen quite easily with all the movies and audio files packaged internally. Copy your A5R file over to the Mac using a CD or a Zip disk. Place this file in your project folder on the Mac desktop. To package the file for the Mac, click on the Mac Packager. You’ll be prompted for the type of Mac you’re packaging for (PPC or 68K), and for the packaged file name. At the end of the packaging, you’ll see a file with the name you selected plus the .PKG extension pop up. This is your Mac packaged file, and it’s equivalent to the .EXE file that you produced for the Windows side.
Special Topics
Creating a Cross Platform CD
You can make a cross platform CD using Adaptec’s ‘Toast’ program on the Mac and a CD burner. If you do not have both of these tools, you will have to get someone else to create your cross-platform CDs. A CD made this way will look like a standard PC CD-ROM to the PC and will look like a standard Mac CD-ROM to the Mac. Very cool.
The basic idea of the cross-platform CD is that the shared files go in one place, the Mac only files in another, and the PC only files, still another.
Before we start let’s get it clear in our minds what’s going where, by making a list.
Shared Folders and Files
All asset folders are in this category. Typically there are folders including ‘Videos,’ ‘Graphics,’ ‘Audio,’ and so on, in this group.
Mac-only Files
Finding the Name of the Mac Hard Drive
Unlike the PC, the Macintosh does not use alpha letters to represent the disk drives and other peripherals. The Mac hard drive is just known as the ‘Macintosh HD’ unless renamed by the owner, which most people do. So the question arises, what do I do if I need to know during runtime the name of my user’s hard drive? You can’t assume something like ‘C:’ as you can on the PC. And you can’t assume ‘Macintosh HD.’ As on the PC, AW creates a records folder on the hard drive (if it’s not there already) as soon as the piece starts. This would occur even if the piece were executing off a CD. So therefore if you parse the System Variable RecordsLocation, and eliminate everything starting with the first ‘:’ (file delimiter) found to the end of the value, you would have the name of the one of the hard drives on the user’s Mac.
Creator Types on the Mac
Creator Types are four-character codes that do approximately the same function as the three character extensions do in Windows filenames – identify the program that created the file. These codes can be used to check for the presence of a program (using BudApi’s baFindApp) or to print a document, and for other uses. Unfortunately, for some reason Apple Computer does not provide documentation for these types. There is a database of 10,000 or so of them available; however, most people only need to know one or two. (http://www.angelfire.com/il/szekely/).
Here are a few creator types:
Acrobat CARO
QuickTime 4 TVOD
Excel 4 XCEL
MSWord msft
WordPerfect WPC2
For a good article on this subject: http://www.mackido.com/Innovation/FileTypeCreator.html
Web Packaging for the Mac
This topic will be covered in a later version of this paper.
Memory Settings on the Mac
People have reported cases of certain graphics behaving strangely on the Mac. In addition to the transparency problem noted above, there can be memory problems with the Mac. In the Mac, the OS does not automatically allocate memory as needed to a program running on the machine. There is a default, but you have to change it manually. To do this, quit the program. Click to highlight it in the Macintosh HD browser. Now, under the ‘Apple’ icon in the upper left of the desktop, select ‘Program Info,’ then select Memory. Now you can increase the default memory allocation. This may help with certain graphics problems.
1 AW= Authorware
2 You open the fontmap.txt file using Notepad on the PC.
3 The exceptions would be any Window-specific System Functions or Variables. There are few of these; be sure to check the documentation when you use a function or a variable.
4 See Control Panel | Multimedia | Devices | Video Compression Codecs
5 There is a FindCD KO that comes with AW 5.X. I have not used it, but this would be another route to go.
#