QuickTime


	Log In \| Not a Member?	Contact ADC

64-bit File Offset Support in QuickTime

Dispatch 22

QuickTime includes comprehensive support for 64-bit file offsets. Releases of QuickTime prior to QuickTime 4 have only supported access to data in media files with 32-bit file offsets. This meant that the maximum addressible media in a single file was 4 GB. QuickTime movies could be created that addressed more data by splitting the movie across multiple files.

OS Limitations

QuickTime 4 added new 64-bit offset version of all APIs that previously accepted a 32-bit offset. While QuickTime can support 64-bit file offsets, QuickTime cannot overcome operating system limitations. Mac OS 9.0 and later, Mac OS X, and Windows 95/98/Me and Windows NT/2000 all support files over 4 GB in size. Under Mac OS versions prior to Mac OS 9, the largest possible file is 2GB (actually slightly smaller). As a result, while the new 64-bit file offset QuickTime APIs can be used on all versions of Mac OS, they only provide access to 2 GB of data per file where the OS only supports files less than 4 GB in size.

Impact on Existing Applications

Existing applications may be used to open movie files which contain 64-bit file offsets. In most cases, these applications will continue to work correctly without any changes. For example, an application which uses QuickTime to play back media files will typically require no changes.

If an API is called, such as GetMediaSampleReference, that can only return a 32 bit offset, but that needs to return a 64-bit offset, an error of fileOffsetTooBigErr (-2125) will be returned.This error has been added specifically to indicate the use of a 32-bit file offset API where a 64-bit file offset needs to be returned.

Recommendation for New Applications

When a new application is being written, it should use the 64-bit versions of the QuickTime APIs. If the application uses the Movie Toolbox, the Sequence Grabber, or Graphics Importers, the 64-bit versions of the APIs can be used in all cases. However, not all Data Handlers implement the 64-bit versions of the APIs. Therefore, applications which call Data Handlers directly should first call the 64-bit version of the API. If that fails and the file offset can be contained in 32-bits, the application should then try the 32-bit version of the API. The example below shows how to obtain the file size from a Data Handler.

OSErr err;
wide fileSize;
   
err = DataHGetFileSize64(dataHandler, &fileSize);
if (err) {
  fileSize.hi = 0;
  err = DataHGetFileSize(dataHandler, &fileSize.lo);
}

The example below shows how to write to a data handler.

OSErr err;
wide *offsetPtr = …
   
err = DataHWrite64(dataH, data, offsetPtr, size, completion, refCon);
if (err && (offsetPtr->hi == 0))
  err = DataHWrite(dataH, data, offsetPtr->lo, size, completion, refCon);

Many applications don't use 64-bit integers, so many programmers aren't familiar with their use. Functions for operating on 64-bit integers are contained in the "Math64.h" interface file.

Movie Toolbox

The following Movie Toolbox functions have been added. Each function is a 64-bit version of an existing API. The only change is that the file offset parameter has been changed from a 32-bit integer to a 64-bit integer.

NewMovieFromDataFork64
GetMovieDataSize64
GetTrackDataSize64
GetMediaDataSize64

AddMediaSampleReferences64 and GetMediaSampleReferences64 have also been added to the Movie Toolbox. The 32-bit file offset versions of these calls accepted a SampleReferenceRecord which contains a 32-bit file offset. The 64-bit versions of this call use the new SampleReference64Record which contains a 64-bit file offset.

struct SampleReference64Record {
	wide			dataOffset;
	unsigned long		dataSize;
	TimeValue		durationPerSample;
	unsigned long		numberOfSamples;
	short 			sampleFlags;
};
typedef SampleReference64Record *SampleReference64Ptr;

Note that no 64-bit file offset version of GetMediaSampleReference or AddMediaSampleReference is provided. Applications should use GetMediaSampleReferences64 and AddMediaSampleReferences64 instead.

Data Handlers

The following Data Handler functions have been added. Each function is a 64-bit version of an existing API. The only change is that the file offset parameter has been changed from a 32-bit integer to a 64-bit integer.

DataHScheduleData64
DataHWrite64
DataHGetFileSize64
DataHPreextend64
DataHSetFileSize64
DataHGetFreeSpace64
DataHAppend64
DataHSetPlayHints64

Sequence Grabber

The Sequence Grabber's API was updated for QuickTime 3.0 to support 64-bit file offsets. At that time, while 64-bit offets could be passed to the Sequence Grabber, only 32-bit file offsets were actually used. The Sequence Grabber now fully implements 64-bit file offset support. Only one new API has been introduced in this release to complete the Sequence Grabber's support for 64-bit file offsets. This call is simply a 64-bit file offset version of an existing 32-bit file offset function.

SGGetStorageSpaceRemaining64

On platforms that support 64-bit file sizes, the maximum output offset for each sequence grabber output is initialized to by a full 64-bit file size. On platforms that support smaller file sizes, the maximum output offset is initialized to the largest available file size. Therefore, on Mac OS the largest file offset that can be used is initialized to 0x7fff0000.

Graphics Importers

The following Graphics Importer functions have been added. Each function is a 64-bit version of an existing API. The only change is that the file offset parameter has been changed from a 32-bit integer to a 64-bit integer.

GraphicsImportGetDataOffsetAndSize64
GraphicsImportReadData64
GraphicsImportSetDataReferenceOffsetAndLimit64
GraphicsImportGetDataReferenceOffsetAndLimit64

As most still image files are well under 4 GB in size, these changes are primarily only useful to those applications which want to use QuickTime to draw still images contained within a larger file, such as a data base.

Movie Importers

The following Movie Importer function hasbeen added. This functionis a 64-bit version of an existing API. The only change is that the file offset parameter has been changed from a 32-bit integer to a 64-bit integer.

MovieImportSetOffsetAndLimit64

Writing Components

If you are writing a component, such as a Data Handler, you will need to implement both 32 and 64-bit file offset versions of some functions. It is recommended that you put the actual implementation of the function in the 64-bit version of the call. The 32-bit version of the call can then simply call the 64-bit version of the function. This is the approach used by QuickTime for its components. Implementing your component in this way will ensure complete compatibility with applications written to work with either 32 or 64-bit file offsets.

QuickTime Movie Files

In order to support 64-bit file offsets, several enhancements were made to the QuickTime File Format. Applications which use QuickTime to access Movie files don't need to be aware of the information in this section, as the Movie Toolbox takes care of these details. Only applications which directly parse the contents of QuickTIme Movie files need to make use of the information presented in this section.

The Sample Table atom now can contain a 64-bit Chunk Offset atom (STChunkOffset64AID = 'co64'). When this atom appears, it is used in place of the original Chunk Offset atom which can only contain 32-bit offsets. When QuickTime writes movie files, it only uses the 64-bit Chunk Offset atom if there are chunks which use the high 32-bits of the chunk offset. Otherwise, the original 32-bit Chunk Offset atom is used to ensure compatibility with previous versions of QuickTime.

QuickTime atoms were previously limited to containing 4 GB of information. It wasn't possible for them to contain more. This had the effect of limiting the amount of data that could be conveniently stored in a QuickTime Movie file to 4 GB. (It is possible to store more using QuickTime atoms, but it is inconvenient, particularly during live capture) Therefore, a 64-bit version of the QuickTime atom has been introduced. QuickTime atoms are a pair of 32-bit values, where the first value is the atom size and the second is the atom type. For a 64-bit atom there are four 32-bit integers, the first value is set to 1, the second is still the atom type, and the last two integers are the 64-bit atom size. By replacing the initial size with 1, the file becomes unreadable to previous versions of QuickTime, as an atom size of 1 was previously illegal.

Files that use the 64-bit version of the QuickTime atom are unreadable by previous versions of QuickTime. For this reason, 64-bit QuickTime atoms are only used when the atom contains more than 4 GB of data.

When writing QuickTime files, it is sometimes necessary to update an atom's size. It is impossible to update a 32-bit atom to a 64-bit atom, as the 32-bit atom is only 8 bytes in size, and the 64-bit atom requires 16 bytes. Therefore, QuickTime will put an 8 byte placeholder atom before any atoms it may have to update the size of. In this way, if the atom needs to be converted from a 32-bit to a 64-bit atom, the placeholder atom can be overwritten to obtain the necessary 8 extra bytes. The placeholder atom has a type of WideAtomPlaceholderType ('wide').

Change History

2/10/99 - jph - First written
6/21/01 - clf - Updated OS version information

Topics
Previous | Next