Programming Do's and Don'ts

Clearly, CD-ROM is a somewhat fragile and imperfect storage medium. But there are things a programmer can do, and avoid doing, to reduce problems, increase data integrity, and increase data rates. This section provides some advice, looking at the following topics:

Making Assumptions about Data Delivery Rates
Handling Data Delays
Alternating File Reads
Testing Performance
Other Things You Should Do

Making Assumptions about Data Delivery Rates

Don't assume a certain data delivery rate from the drive to a data buffer.

Do check the real error code in the IOReq structure before reading from a data buffer to make sure that good data is in the buffer:

err = DoIO(ioReqItem, &ioInfo);
if (err < 0 || (err = ioReq->io_Error) < 0)
    {
    printf(Error getting status:");
    PrintfSysErr(err);
    }

Handling Data Delays

Don't abort out of a task if that task can't read data from a data buffer, or if the task does not receive data as fast as it expects.

Do handle data delays gracefully. For example, an application should not crash if there is a data delay; it should be designed to minimize the problem and glitch in the video stream and continue when it receives the data it needs.

Alternating File Reads

Don't alternate reads, rapidly, between two or more files. This almost always require seeking, which imposes a fairly drastic delay (see section above).

Do consider combining data from many small files (e.g., sound effects) into one file, with a compact table-of-contents at the beginning of the file. At the very least, if you must have two or more files, make sure the files are physically as close to each other on the disc as possible.

Testing Performance

Don't assume that the program's performance when run in development mode (from /remote) is the same as when it's run on a CD-ROM, even if you are running with CD Emulation in Special Mode in the Debugger.

Do test actual performance on a physical CD-ROM disc, in all currently-available 3DO players.

Other Things You Should Do

Issue reads in fairly big chunks (32K or larger) wherever possible.
When possible, use read-ahead buffers before branches to reduce branching seek delays.
Provide adequate buffering to survive a one-revolution delay (up to 150 milliseconds).
If files are used together (e.g., in one level of a game), put them in the same directory.
If files are accessed in a strictly sequential manner, name them in ascending order.
Use data-streaming techniques to combine multiple types of data into a single file which can be read sequentially. This eliminates seeks between files.
Use the Layout Optimizer, which offers the following features:

Attempts to cluster files together on the disc in the same order that they're used during program testing.
Places one avatar of each file into cluster where it's used most frequently.
Attempts to place additional avatars of commonly-used files into other clusters which use the file.
Organizes clusters with most seeks nearest center to reduce latency.
Attempts to place directory avatars near files.
Is very effective at reducing the number of seeks and shortening those seeks which do occur.
Does not guarantee "zero seek" performance.
Greatly improves the titles initial load time by interleaving the files needed for booting (Catapult).