QT.TXT
Remove Frame
INSIDE MACINTOSH
QuickTime
ISBN 0-201-62201-7
1 2 3 4 5 6 7 8 9-MU-9796959493
First Printing, March 1993
pApple Computer, Inc.
(c) 1993, Apple Computer, Inc.
All rights reserved.
No part of this publication may be reproduced, stored in a retrieval
system, or transmitted, in any form or by any means, mechanical,
electronic, photocopying, recording, or otherwise, without prior
written permission of Apple Computer, Inc. Printed in the United States
of America.
No licenses, express or implied, are granted with respect to any
of the technology described in this book. Apple retains all intellectual
property rights associated with the technology described in this book.
This book is intended to assist application developers to develop
applications only for Apple Macintosh computers.
Apple Computer, Inc.
20525 Mariani Avenue
Cupertino, CA 95014
408-996-1010
Apple, the Apple logo, APDA, AppleLink, LaserWriter, Macintosh, and
MPW are trademarks of Apple Computer, Inc., registered in the United
States and other countries.
QuickDraw, QuickTime, and System 7 are trademarks of Apple Computer, Inc.
Adobe Illustrator and PostScript are trademarks of Adobe Systems Incorporated,
which may be registered in certain jurisdictions.
AGFA is a trademark of Agfa-Gevaert.
America Online is a service mark of Quantum Computer Services, Inc.
CompuServe is a registered service mark of CompuServe, Inc.
FrameMaker is a registered trademark of Frame Technology Corporation.
Helvetica and Palatino are registered trademarks of Linotype Company.
Internet is a trademark of Digital Equipment Corporation.
ITC Zapf Dingbats is a registered trademark of International Typeface
Corporation.
Windows is a trademark of Microsoft Corporation.
Simultaneously published in the United States and Canada.
LIMITED WARRANTY ON MEDIA AND REPLACEMENT
ALL IMPLIED WARRANTIES ON THIS MANUAL, INCLUDING IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, ARE LIMITED
IN DURATION TO NINETY (90) DAYS FROM THE DATE OF THE ORIGINAL RETAIL
PURCHASE OF THIS PRODUCT.
Even though Apple has reviewed this manual, APPLE MAKES NO WARRANTY OR
REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS MANUAL,
ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A PARTICULAR
PURPOSE. AS A RESULT, THIS MANUAL IS SOLD AS IS, AND YOU, THE PURCHASER,
ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND ACCURACY.
IN NO EVENT WILL APPLE BE LIABLE FOR DIRECT, INDIRECT, SPECIAL,
INCIDENTAL, OR CONSEQUENTIAL DAMAGES RESULTING FROM ANY DEFECT OR
INACCURACY IN THIS MANUAL, even if advised of the possibility of such damages.
THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF
ALL OTHERS, ORAL OR WRITTEN, EXPRESS OR IMPLIED. No Apple dealer, agent,
or employee is authorized to make any modification, extension, or
addition to this warranty.
Some states do not allow the exclusion or limitation of implied
warranties or liability for incidental or consequential damages, so
the above limitation or exclusion may not apply to you. This warranty gives
you specific legal rights, and you may also have other rights which vary
from state to state.
ED. NOTE: THE FOLLOWING ARE EXCERPTS FROM THE DOCUMENT:
About This Book
This book describes QuickTime, an extension of Macintosh system software
that enables you to integrate time-based data into mainstream Macintosh
applications. This book also provides a complete technical reference
to the Movie Toolbox, the Image Compression Manager, and the movie resources.
Time-based data types contain data that can be stored and retrieved as
values over time. Examples include sound, video, animation, data produced
by scientific instruments, and financial results. Time-based data can
now be manipulated in the same ways as other standard types of data in
the Macintosh environment. In QuickTime, a set of time-based data is
referred to as a movie. This book shows in detail how your application can
allow users to display, edit, cut, copy, and paste movies and movie data
in the same way that they can work with text and graphic elements today.
If you want your application to be able to handle time-based data,
you should first read the chapter Introduction to QuickTime for an
introduction to the QuickTime concepts, architecture, managers, and
components. If you want your application to be able to paste and run
QuickTime movies, to edit them, or to create new movies, you should read
the chapter Movie Toolbox. Your application may only need to paste a
movie from the Clipboard and play it; for example, a word processor might
paste a movie as it does a picture, and the user might use a movie
controller to play the movie. A more media-intensive application might
add the ability to edit the movie after it is pasted; for example,
the user might cut a segment of the movie, add a video segment,
or add a different sound track. Full "mediagenic" applications could create
a movie from disparate sources such as CD tracks, video clips, sounds,
animation from graphics programs, or still images.
If you want your application to use the facilities of QuickTime to compress
and decompress still images, you should read the chapter Image Compression
Manager. These single images are not QuickTime movies; they do not
contain time-based data. Nevertheless, you can use the image compression
and decompression facilities of QuickTime for images that are not stored
in movies. The chapter describes the Image Compression Manager,
including compression and decompression algorithms, and the steps involved
in compressing and decompressing single images and sequences of images.
If you are going to play movies or compress images, you should be
familiar with QuickDraw and Color QuickDraw, described in Inside
Macintosh: Imaging.
If you are going to create QuickTime movies,
you should also be familiar with the Sound Manager, described in Inside
Macintosh: More Macintosh Toolbox, and with the human interface guidelines
as described in Macintosh Human Interface Guidelines. If you are going to use
QuickTime components, you should be familiar with the Component Manager
as described in Inside Macintosh: More Macintosh Toolbox.
If your application imports or exports movies to other platforms,
you should read the chapter Movie Resource Formats. It presents
details of the movie file format used by QuickTime. Most applications do
not need this information.
The companion to this book, Inside Macintosh: QuickTime Components,
includes descriptions of the Apple-supplied QuickTime components:
clock components, compressor components, standard image-compression
dialog components, movie controller components, sequence grabber
components, sequence grabber channel components, sequence grabber
panel components, video digitizer components, media data-exchange
components, preview components, and media handler components.
Format of a Typical Chapter
Almost all chapters in this book follow a standard structure. For
example, the chapter Image Compression Manager contains these sections:
Introduction to the Image Compression Manager.
This section presents a general introduction to image compression.
About Image Compression.
This section provides an overview of the features provided by the
Image Compression Manager.
Using the Image Compression Manager.
This section describes the tasks you can accomplish using the Image
Compression Manager. It describes how to use the most common
functions, gives related user interface information, provides code
samples, and supplies additional information.
Image Compression Manager Reference.
This section provides a complete reference to the Image Compression
Manager by describing the constants, data structures, and functions
that it uses. Each function description also follows a standard
format, which gives the function declaration and description of every
parameter of the function. Some function descriptions also give
additional descriptive information, such as assembly-language
information or result codes.
Summary of the Image Compression Manager.
This section provides the Image Compression Manager's C interface, as
well as the Pascal interface, for the constants, data structures,
functions, and result codes associated with the Image Compression Manager.
Conventions Used in This Book
Inside Macintosh uses various conventions to present information.
Words that require special treatment appear in specific fonts or font
styles. Certain types of information, such as parameter blocks, use
special formats so that you can scan them quickly.
Special Fonts
All code listings, reserved words, and the names of actual data structures,
constants, fields, parameters, and functions are shown in Courier (this
is Courier).
Words that appear in boldface are key terms or concepts and are defined
in the glossary.
Types of Notes
There are several types of notes used in this book.
Note
A note like this contains information that is interesting but possibly
not essential to an understanding of the main text. (An example appears
on page 1-3.)
IMPORTANT
A note like this contains information that is essential for an
understanding of the main text. (An example appears on page 2-84.)
WARNING
Warnings like this indicate potential problems that you should be
aware of as you design your application. Failure to heed these warnings
could result in system crashes or loss of data. (An example appears
on page 2-59.)
Development Environment
The system software functions described in this book are available using
C or Pascal interfaces. How you access these functions depends on the
development environment you are using. This book shows system software
functions in their C interface using the Macintosh Programmer's Workshop
(MPW) version 3.2.
All code listings in this book are shown in C. They show methods of
using various functions and illustrate techniques for accomplishing
particular tasks. All code listings have been compiled and, in most
cases, tested. However, Apple Computer, Inc., does not intend that you
use these code samples in your application.
In a few cases, the functions documented in one chapter may be listed
in the MPW interface files associated with another manager. An example
is the MakeFilePreview function, which is documented for conceptual
consistency in the chapter Movie Toolbox. This function does not
appear in the Movies.h MPW interface file; rather, it is listed in
the ImageCompression.h MPW interface file. When this occurs, the
disparity is noted in the function descriptions.
APDA, Apple's source for developer tools, offers worldwide access to
a broad range of programming products, resources, and information for
anyone developing on Apple platforms. You'll find the most current versions
of Apple and third-party development tools, debuggers, compilers,
languages, and technical references for all Apple platforms. To establish
an APDA account, obtain additional ordering information, or find out about
site licensing and developer training programs, contact
APDA
Apple Computer, Inc.
P. O. Box 319
Buffalo, NY 14207-0319
Telephone: 800-282-2732 (United States)
800-637-0029 (Canada)
716-871-6555 (International)
Fax: 716-871-6511
AppleLink: APDA
America Online: APDA
CompuServe: 76666,2405
Internet: [email protected]
If you provide commercial products and services, call 408-974-4897 for
information on the developer support programs available from Apple.
For information on registering signatures, file types, Apple events,
and other technical information, contact
Macintosh Developer Technical Support
Apple Computer, Inc.
20525 Mariani Avenue, M/S 75-3T
Cupertino, CA 95014-6299
Movie Resource Formats
Contents
Introduction to Movie Resources 4-3
Storing Movies in Files 4-4
Atoms 4-5
Atom Types 4-6
The Layout of a QuickTime Atom 4-7
Overview of the Movie Resource Atom 4-8
Movie Atoms 4-10
Movie Header Atoms 4-11
Track Atoms 4-13
Track Header Atoms 4-14
Media Atoms 4-16
Media Header Atoms 4-17
Handler Reference Atoms 4-18
User-Defined Data Atoms 4-19
Clipping Atoms 4-22
Clipping Region Atoms 4-22
Track Matte Atoms 4-23
Compressed Matte Atoms 4-23
Edit Atoms 4-24
Edit List Atoms 4-25
Media Information Atoms 4-26
Video Media Information Atoms 4-26
Video Media Information Header Atoms 4-27
Sound Media Information Atoms 4-28
Sound Media Information Header Atoms 4-29
Data Information Atoms 4-30
Data Reference Atoms 4-32
An Introduction to Samples 4-32
Sample Table Atoms 4-33
Sample Description Atoms 4-35
Time-to-Sample Atoms 4-36
Sync Sample Atoms 4-38
Sample-to-Chunk Atoms 4-39
Sample Size Atoms 4-41
Chunk Offset Atoms 4-42
Shadow Sync Atoms 4-44
Using Media Information Atoms 4-45
Finding a Sample 4-46
Finding a Key Frame 4-46
Movie Resource Formats
This chapter describes the format of QuickTime movie resources.
Movie resources are the data structures that provide the medium
of exchange for movie data. Movie resources may be exchanged between
applications on a single Macintosh computer or between applications on
several Macintosh and non-Macintosh computers.
IMPORTANT
The information in this chapter is intended for developers who need
to know about the content of movie resources. You need to learn about
movie resources if you want to create movies on other computer
environments and import them to the Macintosh environment, or
if you want to interpret QuickTime movies on other types of
computers. Developers of Macintosh applications do not need
to know about the layout of movie resources--the Movie Toolbox
functions handle the details of movie storage and exchange.
This chapter describes atoms, the basic storage elements that,
taken together, make up a movie resource.
The chapter is divided into the following major sections:
Storing Movies in Files describes the two ways that QuickTime
movies may be stored in files.
Atoms describes the format and content of the most basic movie
storage element and the standard atoms that may be found in a
movie resource.
Overview of the Movie Resource Atom provides a look at the movie
resource structure of a QuickTime movie.
Using Media Information Atoms provides examples of the media information
atoms.
To understand fully the information presented in this chapter, you should
be familiar with the Movie Toolbox (see the chapter Movie Toolbox in
this book.) In particular, you should read about the characteristics
of movie, track, and media structures.
If you are developing a movie application that runs on another type of
computer, you do not have the facilities of the Movie Toolbox available
to you. If you want that application to exchange data with QuickTime
applications on the Macintosh computer, you need to know the format of
QuickTime movie resources.
Introduction to Movie Resources
Movie resources define the data interchange format for movies. The Movie
Toolbox allows your application to create, view, edit, and store QuickTime
movies. The functions of the Movie Toolbox shield your program from
the details of how a movie is stored in the Macintosh file system (in
the file type 'moov'.) As a result, applications that run on
Macintosh computers do not need to know anything about the internal
structures of movie resources or movie files.
Storing Movies in Files
In the Macintosh file system, the Movie Toolbox typically uses both the
resource fork and the data fork to store a QuickTime movie. The resource
fork contains the movie resource. The data fork contains the actual movie
data
To facilitate data exchange between Macintosh computers and other computers,
the Movie Toolbox can also understand movie files that store all the
information for a movie in the data fork. These movie files are called
single-fork movie files. Single-fork movie files are a possible way
to export QuickTime movies to other systems, such as a computer using
QuickTime for Windows.
Your application can create single-fork movie files from normal movie
files by calling the Movie Toolbox's FlattenMovieData function (see
the chapter "Movie Toolbox" for more information about this function.)
Your application can read single-fork movie files using the standard
Movie Toolbox functions--you do not need to perform any special
processing.
Figure 4-1 shows the difference between single-fork and normal movie
files. A standard Macintosh movie file contains information in both
the data and resource forks. A single-fork movie file contains a data
fork.
ED.NOTE: Figures are not available in this plain text version
of the specification.
Figure 4-1 Movie files and single-fork movie files
Single-fork movie files store all the information for a movie in the
data fork. The data fork contains two atoms: a movie data atom ('mdat')
and a movie resource atom. The movie's media data is stored in the
movie data atom. Other atoms may follow the movie data atom. The movie
resource atom follows the movie data atom and holds the description of
the movie. There is no resource fork for this kind of movie file.
Figure 4-2 shows the layout of a single-fork movie file. The movie
data atom contains no other atoms, whereas the movie atom may contain
other atoms.
Figure 4-2 The structure of a single-fork movie file
Atoms
The basic data unit in a QuickTime movie resource is the atom. Each
atom contains size and type information along with its data. The size
field indicates the number of bytes in the atom, including the size
and type fields. The type field specifies the type of data stored in
the atom and, by implication, the format of that data.
Atom Types
Table 4-1 lists the atom types defined by Apple and their
corresponding constants and atom names.
Table 4-1 Apple-defined atom types
Constant Atom type Atom name
-------- --------- ---------
MovieAID 'moov' Movie atom
MovieHeaderAID 'mvhd' Movie header atom
ClipAID 'clip' Clipping atom
RgnClipAID 'crgn' Clipping region atom
MatteAID 'matt' Track matte atom
MatteCompAID 'kmat' Compressed matte atom
TrackAID 'trak' Track atom
UserDataAID 'udta' User-defined data atom
TrackHeaderAID 'tkhd' Track header atom
EditsAID 'edts' Edit atom
EditsListAID 'elst' Edit list atom
MediaAID 'mdia' Media atom
MediaHeaderAID 'mdhd' Media header atom
MediaInfoAID 'minf' Media information atom
VideoMediaInfoHeaderAID 'vmhd' Video media information header atom
SoundMediaInfoHeaderAID 'smhd' Sound media information header atom
DataInfoAID 'dinf' Data information atom
DataRefAID 'dref' Data reference atom
SampleTableAID 'stbl' Sample table atom
STSampleDescAID 'stsd' Sample description atom
STTimeToSampAID 'stts' Time-to-sample atom
STSyncSampleAID 'stss' Sync sample atom
STShadowSyncAID 'stsh' Shadow sync atom
STSampleToChunkAID 'stsc' Sample-to-chunk atom
HandlerAID 'hdlr' Handler reference atom
STSampleSizeAID 'stsz' Sample size atom
STChunkOffsetAID 'stco' Chunk offset atom
The Layout of a QuickTime Atom
Figure 4-3 shows the layout of a sample QuickTime atom. Each atom
carries its own size and type information as well as its data.
Throughout this chapter, the name of a container atom (an atom that
contains other atoms, including other container atoms) is printer
across a horizontal gray band, and the name of a leaf atom (an atom
that contains no other atoms) is printed across a horizontal drop
shadow box. Leaf atoms contain data, usually in the form of tables.
Figure 4-3 A sample QuickTime atom
Overview of the Movie Resource Atom
Movie resources consist of movie atoms, which in turn contain track
atoms, which in turn contain media atoms (see the chapter Movie
Toolbox in this book for information about the relationships between
movies, tracks, and media structures). Leaf atoms usually contain
tables of data. For example, the track atom contains the edit atom,
which contains a leaf atom called the edit list atom. The edit list
atom contains an edit list table. (See Figure 4-15 on page 4-24 for an
illustration of the edit atom, and see Figure 4-16 on page 4-25 for an
illustration of the edit list table).
Figure 4-4 provides a conceptual view of the organization of a
QuickTime movie, which, in this case, has one track containing video
information. Each nested box in the illustration represents an atom
that belongs to the atom underlying it. The figure does not show the
data regions of any of the atoms. These areas are described in the
pertinent sections that follow.
Figure 4-4 Sample organization of a one-track video movie
Movie Atoms
You can use movie atoms to specify information that defines a
movie. The movie atom contains the movie header atom, which defines
the time scale and duration information for the entire movie, as well
as its display characteristics. In addition, the movie atom contains
each track in the movie.
The movie atom has an atom type of 'moov'. It contains other types of
atoms, including one leaf atom--the movie header ('mvhd')--and several
atoms that contain other atoms: a clipping atom ('clip'), one or more
track atoms ('trak'), and user-defined data ('udta').
Figure 4-5 shows the layout of a movie atom. The movie header atom is
the only required atom in the movie atom.
Figure 4-5 The layout of a movie atom
You define a movie atom by specifying these elements:
* Size. The number of bytes in this movie atom.
* Type. The type of this movie atom (the atom type, 'moov').
* Movie header. The movie header atom associated with this movie. See
the next section for details on the movie header atom.
* Movie clipping atom. The clipping atom associated with this
movie. See Clipping Atoms, which begins on page 4-22, for more
information.
* Track list. One or more track atoms associated with this movie. See
Track Atoms, which begins on page 4-13, for details on track atoms
and their associated atoms.
* User data. The user-defined data atom associated with this movie. See
User-Defined Data Atoms, which begins on page 4-19, for a discussion
of user-defined data.
Movie Header Atoms
You can use the movie header atom to specify the characteristics of an
entire movie. Figure 4-6 shows the layout of the movie header
atom. The movie header atom is a leaf atom, which contains time
information for the entire movie, such as time scale and duration. It
also illustrates the data stream specified in the matrix structure field.
Figure 4-6 The layout of a movie header atom
You define a movie header atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this
movie header atom.
* Type. A long integer that specifies the format of the data in this
movie header atom (defined by the atom type, 'mvhd').
* Version. A 1-byte specification of the version of this movie header
atom.
* Flags. Three bytes of space for future movie header flags.
* Creation time. A long integer that specifies (in seconds since
midnight, January 1, 1904) when the movie atom was created.
* Modification time. A long integer that specifies (in seconds since
midnight, January 1, 1904) when the movie atom was changed.
* Time scale. A time value that indicates the time scale for this
movie--that is, the number of time units that pass per second in its
time coordinate system. A time coordinate system that measures time in
sixtieths of a second, for example, has a time scale of 60.
* Duration. A time value that indicates the duration of the movie in
time scale units.
* Preferred rate. A fixed number that specifies the rate at which to
play this movie.
* Preferred volume. A 16-bit fixed number that specifies how loud to
play this movie's sound.
* Reserved. Ten bytes reserved for use by Apple. Set to 0.
* Matrix. The matrix structure associated with this movie. A matrix
shows how to map points from one coordinate space into another
coordinate space. See the chapter Movie Toolbox in this book for
details on matrix structures.
* Preview time. The time value in the movie at which the preview
begins.
* Preview duration. The duration of the movie preview in movie time
scale units. For more on time, see the chapter Movie Toolbox in this
book.
* Poster time. The time value of the time of the movie poster.
* Selection time. The time value for the start time of the current
selection.
* Selection duration. The duration of the current selection in movie
time scale units.
* Current time. The time value for current time position within the
movie.
* Next track ID. A long integer that indicates a value to use for the
track ID number of the next track added to this movie.
Track Atoms
Track atoms define a single track of a movie. A movie may consist of
one or more tracks. Each track is independent of the other tracks in
the movie and carries its own temporal and spatial information. Each
track atom contains its associated media atom. Figure 4-7 shows the
layout of a track atom. The track atom requires the track header atom
and the media atom.
Figure 4-7 The layout of a track atom
The track atom contains a track header atom ('tkhd'), a track clipping
atom ('clip'), a track matte atom ('matt'), an edit atom ('edts'), a
media atom ('mdia'), and a user-defined data atom ('udta'). You define
a track atom by specifying these elements:
* Size. The number of bytes in this track atom.
* Type. The type of this track atom (the atom type, 'trak').
* Track header. The track header atom associated with this track. See
the next section for details.
* Track clipping. The track clipping atom associated with this
track. See Clipping Atoms, which begins on page 4-22, for more on
clipping atoms.
* Track matte. The track matte atom associated with this track. See
Track Matte Atoms, which begins on page 4-23, for more on track
matte atoms.
* Edits. The edit atom associated with this track. See Edit Atoms,
which begins on page 4-24, for details.
* Media. The media atom associated with this track. See Media Atoms,
which begins on page 4-16, for details.
* User data. The user-defined data atom associated with this
track. This field is used for extension with new data types. See
User-Defined Data Atoms, which begins on page 4-19 for details.
Track Header Atoms
The track header atom specifies the characteristics of a single track
within a movie. A track header atom contains a size field that
specifies the number of bytes and a type field that indicates the
format of the data (defined by the atom type, 'tkhd'). Figure 4-8
shows the structure of the track header atom.
Figure 4-8 The layout of a track header atom
The track header atom contains the track characteristics for the
track, including temporal, spatial, and volume information. You define
a track header atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this
track header atom.
* Type. A long integer that specifies the type of data in this track
header atom (defined by the atom type, 'tkhd').
* Version. A 1-byte specification of the version of this track header.
* Track header flags. Three bytes that are reserved for the track
header flags, which adjust the remaining fields in the track header
according to the kind of movie track you specify with the following
enumeration:
enum
{
TrackEnable = 1<<0, /* enabled track */
TrackInMovie = 1<<1, /* track in playback */
TrackInPreview = 1<<2, /* track in preview */
TrackInPoster = 1<<3 /* track in poster */
};
* Creation time. A long integer that indicates (in seconds since
midnight, January 1, 1904) when the track header was created.
* Modification time. A long integer that indicates (in seconds since
midnight, January 1, 1904) when the track header was changed.
* Track ID. A long integer that specifies the value to use for the
track ID number.
* Reserved. A long integer that is reserved for use by Apple. Set the
value of this field to 0.
* Duration. The duration of this track (in movie time).
* Reserved. An 8-byte value that is reserved for use by Apple. Set the
value of this field to 0.
* Layer. The priority of playing this track in a movie. When it plays
a movie, the Movie Toolbox displays the movie's tracks according to
their layer--tracks with lower layer numbers are displayed in front;
tracks with higher layer numbers are displayed in back.
* Alternate group. A short integer that specifies a collection of
movie tracks that contain alternate data for one another. QuickTime
chooses one track from the group to be used when the movie is played.
The choice may be based on such considerations as playback quality or
language and the capabilities of the computer.
* Volume. A short integer that indicates how loudly this track's sound
is to be played.
* Reserved. A short integer that is reserved for use by Apple. Set the
value of this field to 0.
* Matrix. The matrix structure associated with this track. See Figure
4-6 on page 4-11 for an illustration of a matrix structure.
* Track width. A fixed number that specifies the width of this track.
* Track height. A fixed number that indicates the height of this
track.
Media Atoms
Media atoms define the data for a movie track. The media atom contains
information that specifies the component that is to interpret the
media data, and it also specifies the data references. Figure 4-9
shows the layout of a media atom.
Figure 4-9 The layout of a media atom
The media atom has an atom type of 'mdia'. It may contain other atoms,
such as a media header ('mdhd'), a handler reference ('hdlr'), media
information ('minf'), and user-defined data ('udata'). The only
requred atom in a media atom is the media header atom.
Note
The handler reference atom lets you know what kind of media this media
atom contains--for example, video or sound. The layout of the media
information atom is specific to the media handler that is to interpret
the media. Media Information Atoms, which begins on page 4-26,
discusses how data may be stored in a media, using the video media
format defined by Apple as an example.
You define a media atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this media
atom.
* Type. A long integer that specifies the type of the data in this
media atom (defined by the 'mdia' atom type).
* Media header. The media header atom, which is described in the next
section. It contains the standard media information.
* Media handler. The media handler, which is defined by the handler
reference atom, described in Handler Reference Atoms, which begins
on page 4-18.
* Media information. The media information atom. For an example of a
media information atom, see Video Media Information Atoms, which
begins on page 4-26.
* User data. The user-defined data atom associated with this
media. This field is used for extension with new data types. See
User-Defined Data Atoms, which begins on page 4-19, for details.
Media Header Atoms
The media header atom specifies the characteristics of the media that
is used to store data for the movie track defined in its associated
track atom. The media header atom contains the number of bytes in the
media header atom, the format of the data in the media header atom
(defined by the 'mdhd' atom type), and the media header. The media
characteristics include temporal information. Figure 4-10 shows the
layout of the media header atom.
Figure 4-10 The layout of a media header atom
You define a media header atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this
media header atom.
* Type. A long integer that specifies the type of data in this media
header atom (defined by the atom type, 'mdhd').
* Version. One byte that specifies the version of this movie.
* Flags. Three bytes of space for future media header flags.
* Creation time. A long integer that specifies (in seconds since
midnight, January 1, 1904) when the media atom was created.
* Modification time. A long integer that specifies (in seconds since
midnight, January 1, 1904) when the media atom was changed.
* Time scale. A time value that indicates the time scale for this
media--that is, the number of time units that pass per second in its
time coordinate system.
* Duration. The duration of this media in media time scale units.
* Language. A short integer that specifies the language code for this
media. See Inside Macintosh: Text for more on language codes.
* Quality. A short integer that specifies the playback quality (that
is, its suitability for playback in a given environment) for this
media. See the chapter Movie Toolbox in this book for details on
playback quality.
Handler Reference Atoms
The handler reference atom specifies the component that is to
interpret a media's data. This component is called a media
handler. (See the chapter Component Manager in Inside Macintosh: More
Macintosh Toolbox for more information about components.) Figure 4-11
shows the layout of a handler reference atom.
Figure 4-11 The layout of a handler reference atom
You define a handler reference atom by specifying these elements:
* Size. The number of bytes in this handler reference atom.
* Type. The type of the data (defined by the 'hdlr' atom type) in the
handler reference atom.
* Flags. A 1-byte specification of the version of this handler
information.
* Version. A 3-byte space for future handler information flags.
* Component type. A four-character code that identifies the type of
the media handler. All components of a particular type must support a
common set of functions. Examples of component types are 'mhlr' and
dhlr'.
* Component subtype. A four-character code that identifies the type of
the media handler. Different types of a component type may support
additional features or provide interfaces that extend beyond the
standard functions for a given component type value. For media
handlers, this field defines the type of data--for example, 'vide' or
'soun'.
* Component manufacturer. A four-character code that identifies the
manufacturer of this media handler. This field allows for further
differentiation between indicidual components. For example, components
made by a specific manufacturer may support an extended feature set.
* Component flags. A 32-bit field that provides additional information
about a particular media handler. The most significant 8 bits are
reserved for use by the Component Manager and provide both static and
dynamic information about the component.
* Component flags mask. A 32-bit field that indicates which flags in
the component mask are relevant to a particular search
operation. These flags are used when searching for a handler component.
* Component name. A Pascal string that specifies the name of the
component--that is, the original handler used when this movie was
created.
User-Defined Data Atoms
Many movie, track, and media atoms contain atoms that store
user-defined data. Your application may store data in these
user-defined data atoms.
Figure 4-12 shows the layout of a user-defined data atom.
Figure 4-12 The layout of a user-defined data atom
You define a user-defined data atom by specifying these elements:
* Size. The number of bytes in the data element.
* Type. The type of the data in the data element (defined by the
'udta' atom type).
* User data list. The movie user data atom contains a user data list
that is itself formatted like a series of atoms. Each data element in
the private data portion of the user-defined data atom contains size
and type information along with the data. Furthermore, the list of
atoms is optionally terminated by a 0.
The following user data types are currently defined:
'(c)cpy' Copyright statement
'(c)day' Date the movie content was created
'(c)dir' Name of movie's director
'(c)ed1' to
'(c)ed9' Edit dates and descriptions
'(c)fmt' Indication of movie format (computer-generated, digitized,
and so on)
'(c)inf' Information about the movie
'(c)prd' Name of movie's producer
'(c)prf' Names of performers
'(c)req' Special hardware and software requirements
'(c)src' Credits for those who provided movie source content
'(c)wrt' Name of movie's writer
User data items of these types must contain text data only.
Clipping Atoms
Clipping atoms specify the clipping regions for movies and for
tracks. Figure 4-13 shows the layout of clipping atoms.
Figure 4-13 The layout of a clipping atom
You define a clipping atom by specifying these elements:
* Size. The number of bytes in this clipping atom.
* Type. The type of the data in this clipping atom (defined by the
'clip' atom type).
* Clipping region atom. Described in the next section.
Clipping Region Atoms
The clipping region atom specifies the clipping data. The layout of
the clipping region atom is shown in Figure 4-13. You define a
clipping region atom by specifying these elements:
* Size. A long integer that indicates the number of bytes in the
clipping region data atom.
* Type. A long integer that indicates the type of the clipping region
data (defined by the 'crgn' atom type).
The region size, region boundary box, and data fields constitute a
QuickDraw region. See the chapter QuickDraw in Inside Macintosh:
Imaging for details on QuickDraw regions.
Track Matte Atoms
Track matte atoms specify the mattes for tracks. (A track matte is a
pixel map that defines the blending of visual track data. See the
chapter Movie Toolbox in this book for details.) Figure 4-14 shows the
layout of track matte atoms.
Figure 4-14 The layout of a track matte atom
You define a track matte atom by specifying these elements:
* Size. A long integer that specifies that number of bytes in this
track matte atom.
* Type. A long integer that specifies the type of this track matte atom
(defined by the 'matt' atom type).
* Compressed matte atom. The compressed matte atom, which is described
in the next section.
Compressed Matte Atoms
The compressed matte atom specifies the image description structure
associated with a particular matte atom. The layout of the compressed
matte atom is shown in Figure 4-14.
You define a compressed matte atom by specifying these elements:
* Size. A long integer that indicates the number of bytes in this
compressed matte atom.
* Type. A long integer that indicates the type of the data in this atom
(defined by the 'kmat' atom type).
* Version. A 1-byte specification of the version of this compressed
matte atom.
* Flags. Three bytes of space for future flags associated with this
compressed matte atom.
* Matte image description. An image description structure of variable
length and associated with this matte data. See the chapter Image
Compression Manager in this book for details on the image description
structure.
* Matte data. The compressed matte data, which is of variable length.
Edit Atoms
You can use edit atoms to define the portions of the media that are to
be used to build up a track for a movie. Figure 4-15 shows the layout
of an edit atom.
Note
If the edit atom or the edit list atom is missing, you can assume that
the entire media is contained in the track.
Figure 4-15 The layout of an edit atom
You define an edit atom by specifying these elements:
* Size. A long integer that indicates the number of bytes in this edit
atom.
* Type. A long integer that indicates the type of the data in this edit
atom (defined by the 'edts' atom type).
* Edit list. The edit list atom that contains the edit list
information, described in the next section.
Edit List Atoms
You can use the edit list atom, also shown in Figure 4-15, to tell
QuickTime how to map from a time in a movie to a time in a media, and
ultimately to media data. This information is in the form of an edit
list table, shown in Figure 4-16.
You define an edit list atom by specifying the following elements:
* Size. A long integer that specifies the number of bytes in the edit
list atom.
* Type. A long integer that specifies the type of the edit list data
(defined by the 'elst' atom type).
* Version. A 1-byte specification of the version of this edit list
atom.
* Flags. Three bytes of space for future flags to be associated with
this edit list atom.
* Number of entries. The number of entries in the edit list atom.
* Edit list table. Each entry in the edit list table (shown in Figure
4-16) describes a single edit and contains a track duration field, a
media time field, and a media rate field.
Figure 4-16 The layout of an edit list table
You create an edit list table by specifying these elements:
* Track duration. The duration of this edit segment in movie time scale
units.
* Media time. The starting time within the media of this edit segment
(in media time scale units). If -1, it is an empty edit.
* Media rate. A fixed number that specifies the relative rate at which
to play the media for this edit segment.
Media Information Atoms
Media information atoms (defined by the 'minf' data type) store
handler-specific information for the media data that constitutes a
track. The media handler uses this information to map from media time
to media data. These atoms are formatted differently based on the type
of media data stored in the atom. The format and content of media
information atoms are dictated by the media handler that is
responsible for interpreting the media data stream. Another media
handler would not know how to interpret this information. This section
describes examples of atoms that store media information for the video
(defined by the 'vmhd' atom type) and sound (defined by the 'smhd'
atom type) portions of QuickTime movies.
Note
Using Media Information Atoms, which begins on page 4-45, discusses
how the video media handler locates samples in a video media.
Video Media Information Atoms
Video media information atoms are the highest-level atoms in video
media. A number of other atoms define specific characteristics of the
video media data. Figure 4-17 shows the layout of a video media
information atom.
Figure 4-17 The layout of a media information atom for video
You define a video media information atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this video
media information atom.
* Type. A long integer that specifies the type of the data (defined by
the 'minf' atom type) in this media information header.
* Video media information. The video media information header atom (a
required atom), which is described in the next section.
* Handler reference. The handler reference atom (a required atom),
which contains information specifying the data handler component that
provides access to the media data. See the chapter Component Manager in
Inside Macintosh: More Macintosh Toolbox for more information about
components. Figure 4-11 on page 4-18 shows the layout of a handler
reference atom. The handler reference uses the data information atom,
described by the datainfo field in the video media information
structure.
* Data information. The data information atom, described in Data
Information Atoms on page 4-30.
* Sample table. The sample table atom, described in Sample Table
Atoms on page 4-33.
Video Media Information Header Atoms
Video media information atoms are the highest-level atoms in video
media. A number of other atoms define specific characteristics of the
video media ddata. Figure 4-18 shows the structure of a video media
information header atom.
Figure 4-18 The layout of a media information header atom for video
You define a video media information header atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in the media
information in this video media information header.
* Type. A long integer that specifies the type of the data (defined by
the 'vmhd' atom type) in this video media information header.
* Version. A 1-byte specification of the version of this video media
information header.
* Flags. A 3-byte space for video media information flags. The
videoFlagNoLeanAhead flag is available, which instructs QuickTime that
the video was not created skewed and that it should use a technique
having greater accuracy.
* Graphics mode. A short integer that specifies the transfer mode,
which is a specification of which Boolean operation QuickDraw should
perform when drawing or transferring an image from one location to another.
* Opcolor. Three 16-bit values that specify the red, green, and blue
colors for the transfer mode operation indicated in the graphics mode
field.
For comprehensive details on QuickDrawUs transfer modes and opcolors
and their values, see Inside Macintosh: Imaging.
Sound Media Information Atoms
Sound media information atoms are the highest-level atoms in sound
media. These atoms define specific characteristics of the sound media
data. Figure 4-19 shows the layout of a sound media information atom.
Figure 4-19 The layout of a media information atom for sound
In addition to the size and type information, the sound media
information atom contains the sound media information header atom,
which is described in the next section, and the handler reference
atom, the data information atom, and the sample table atom.
You define a sound media information atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this sound
media information atom.
* Type. A long integer that specifies the type of the data in this
sound media information header (defined by the 'minf' data type).
* Sound media information. The sound media information header atom (a
required atom), which is described in the next section.
* Handler reference. The handler reference atom (a required atom),
which contains information specifying the data handler component that
provides access to the media data. See the chapter Component Manager
in Inside Macintosh: More Macintosh Toolbox for more information about
components. Figure 4-11 on page 4-18 shows the layout of a handler
reference atom. The handler reference atom uses the data information
atom, described by the dataInfo field in this sound media information
structure.
* Data information. The data information atom, described in Data
Information Atoms, which begins on page 4-30.
* Sample table. The sample table atom, described in Sample Table
Atoms, which begins on page 4-33.
Sound Media Information Header Atoms
The sound media information header atom (shown in Figure 4-20) stores
the sound media information.
Figure 4-20 The layout of a sound media information header atom
You define a sound media information header atom by specifying these
elements:
* Size. A long integer that specifies the number of bytes in this sound
media information header atom.
* Type. A long integer that specifies the type of the data in this
sound media information header atom (defined by the 'smhd' data type).
* Version. A 1-byte specification of the version of this sound media
information header.
* Flags. Three bytes of space for future associated flags.
* Balance. A short integer that specifies the sound balance of this
sound media. (Sound balance is the setting that controls the mix of
sound between the two speakers of a computer.) This field is normally
set to 0. See the chapter Movie Toolbox in this book for more on sound
balance.
* Reserved. Reserved for use by Apple. Set this field to 0.
Data Information Atoms
The handler reference atom (described in Handler Reference Atoms,
which begins on page 4-18) contains information specifying the data
handler component that provides access to the media data. See the
chapter Component Manager in Inside Macintosh: More Macintosh Toolbox
for more about components. The handler uses the data information atom,
which you can use to specify where the media data is stored. Figure
4-21 shows the layout of the data information atom.
Figure 4-21 The layout of a data information atom
You define a data information atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this data
information atom.
* Type. A long integer that specifies the format (defined by the 'dinf'
atom type) of the data in this data information atom.
* Data references. The data reference atom, described in the next
section, contains the data references.
Data Reference Atoms
Figure 4-21 also shows the data reference atom, which encompasses the
data references.
You define a data reference atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this data
reference container atom.
* Type. A long integer that specifies the type of the data in the data
reference atom (defined by the 'dref' data type).
* Version. A 1-byte specification of the version of this data reference
atom.
* Flags. Three bytes that contain space for future flags.
* Number of entries. A count of entries in the data references field.
* Data references. Data references are formatted like atoms, as
follows:
* Size. A long integer that specifies the number of bytes in these data
references.
* Type. A long integer that specifies the type of the data (currently
defined by the 'alis' data type on the Macintosh computer) in the data
references.
* Version. A 1-byte specification of the version of these data
references.
* Flags. Three bytes that contain the attributes of the data in these
data references. One enumerated constant is available. The
dataRefSelfReference attribute denotes that the data comes from the
same location as the movie resource. If the movie resource came from a
resource fork, the movie data is in the data fork of the same file. In
the case of a single-fork file, the movie data is also in the data
fork of the file.
* Data references. The data reference information. (For the current
data handlers, this is an alias).
An Introduction to Samples
One way to describe a sample (that is, a single element of a sequence
of time-ordered data) is to include it in a sample table atom. Samples
are stored sequentially in the media, and they may have varying
durations. This approach enforces an ordering of the samples--it does
not mean the sample data must be stored sequentially with respect to
movie time in the actual data stream. Figure 4-22 shows the way that
samples are stored in a series of chunks in a media. Chunks are a
collection of data samples in a media that allow optimized data
access. A chunk may contain one or more samples. Chunks in a media may
have different sizes, and the samples within a chunk may have
different sizes.
Figure 4-22 Samples in a media
Sample Table Atoms
The sample table atom contains information for converting from media
time to sample number to sample location. This atom also indicates how
to interpret the sample (for example, whether to decompress the video
sample and, if so, how). This section describes the format and content
of the sample table atom.
The sample table has an atom type of 'stbl'. It contains the sample
description atom, the time-to-sample atom, the sample-to-chunk atom,
the sync sample atom, the sample size atom, the chunk offset atom, and
the shadow sync atom.
Figure 4-23 shows the layout of the sample table atom.
Figure 4-23 The layout of a sample table atom
You define a sample table atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in the sample
table atom.
* Type. A long integer that specifies the type of the data (defined by
the 'stbl' atom type) in the sample table atom.
* Sample description. The sample description atom, described in the
next section.
* Time-to-sample. The time-to-sample atom, described in Time-to-Sample
Atoms, which begins on page 4-36.
* Sync sample. The sync sample atom, described in Sync Sample Atoms,
which begins on page 4-38.
* Sample-to-chunk. The sample-to-chunk atom, described in
Sample-to-Chunk Atoms, which begins on page 4-39.
* Sample size. The sample size atom, described in Sample Size Atoms,
which begins on page 4-41.
* Chunk offset. A chunk offset atom, described in Chunk Offset Atoms,
which begins on page 4-42.
* Shadow sync. The shadow sync atom, described in Shadow Sync Atoms,
which begins on page 4-44.
The following sections discuss each of the atoms that may be contained in a sample table.
Sample Description Atoms
The sample description atom stores information for the decoding of
samples in the media. In the case of video media, the sample
descriptions are image description structures (see the chapter Image
Compression Manager earlier in this book for more information about
image descriptions). Figure 4-24 shows the layout of the sample
description atom.
The sample description atom has an atom type of 'stsd'. The sample
description atom contains a table of sample descriptions, each of
which contains a single sample description. A media may have one or
more sample descriptions, depending upon the number of different
compression types used in the media. The sample-to-chunk atom
identifies the sample description for each sample in the media by
specifying the index into this table for the appropriate description
(see Sample-to-Chunk Atoms, which begins on page 4-39).
Figure 4-24 The layout of a sample description atom
You define a sample description atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this
sample description atom.
* Type. A long integer that specifies the type (defined by the atom
type 'stsd') of the data in this sample description atom.
* Version. A 1-byte specification of the version number of this sample
description atom.
* Flags. Three bytes of space for future flags associated with it.
* Number of entries. A long integer that specifies how many entries in
the sample description table are listed in the sample description
table field of this atom.
* Sample description table. The sample description table, which
contains a list of sample descriptions.
Time-to-Sample Atoms
Time-to-sample atoms store duration information for the samples in a
media, providing a mapping from a time in a media to the corresponding
data sample. The time-to-sample atom has an atom type of 'stts'.
You can determine the appropriate sample for any given time in a media
by examining the time-to-sample atom (shown in Figure 4-25), which
contains the time-to-sample atom table.
Figure 4-25 The layout of a time-to-sample atom
You define a time-to-sample atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this
time-to-sample atom.
* Type. A long integer that specifies the type (defined by the 'stts'
atom type) of the data contained in the time-to-sample atom.
* Version. A 1-byte specification of the version number of this
time-to-sample atom.
* Flags. Three bytes of space for any future flags associated with this
time-to-sample atom.
* Number of entries. A long integer that specifies the number of
entries in the time-to-sample table.
* Time-to-sample table. The time-to-sample atom contains a table that
defines the duration of each sample in the media. Each table entry
contains a count field and a duration field. The structure of the
time-to-sample table is shown in Figure 4-26.
Figure 4-26 The layout of a time-to-sample table
You define a time-to-sample table by specifying these entries:
* Sample count. A long integer that specifies the number of consecutive
samples that have the same duration.
* Sample duration. A long integer that specifies the duration of each
sample.
Entries in the table collect samples according to their order in the
media and their duration. If consecutive samples have the same
duration, a single table entry may be used to define more than one
sample. In these cases, the count field indicates the number of
consecutive samples that have the same duration. For example, if a
video media has a constant frame rate, this table would have one entry.
Figure 4-27 shows an example of a time-to-sample table that is based
on the data stream shown in Figure 4-22 on page 4-33. Figure 4-22
shows a total of nine samples that correspond in count and duration to
the entries of the table shown in Figure 4-27. Even though samples 4,
5, and 6 are in the same chunk, sample 4 has a duration of 3, and
samples 5 and 6 have a duration of 2.
Figure 4-27 An example of a time-to-sample table
Sync Sample Atoms
The sync sample atom identifies the key frames in the media. In a
media that contains compressed data, key frames define starting points
for portions of a temporally compressed sequence (see the chapter
Image Compression Manager in this book for more information about key
frames and temporal compression in video data). The key frame is
self-contained--that is, it is independent of preceding frames.
Subsequent frames may depend on the key frame.
Sync sample atoms have an atom type of 'stss'. The sync sample atom
contains a table of sample numbers. Each entry in the table identifies
a sample that is a key frame for the media. Figure 4-28 shows the
layout of a sync sample atom.
If no sync sample atom exists, then all the samples are key frames.
Figure 4-28 The layout of a sync sample atom
You define a sync sample atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this sync
sample atom.
* Type. A long integer that specifies the type of the data of this sync
sample atom (defined by the 'stss' atom type).
* Version. A 1-byte specification of the version of this sync sample
atom.
* Flags. Three bytes of space for future flags.
* Number of entries. A long integer that specifies how many sample
numbers are in the sync sample table contained in the sync sample
table field.
* Sync sample table. The sync sample table (shown in Figure 4-29)
consists of an array of sample numbers. Each entry in the table
identifies a sample that is a key frame for the media.
Figure 4-29 The layout of a sync sample table
Sample-to-Chunk Atoms
As samples are added to a media, they are collected into chunks that
allow optimized data access. A chunk may contain one or more samples.
Chunks in a media may have different sizes, and the samples within a
chunk may have different sizes. The sample-to-chunk atom stores chunk
information for the samples in a media. Figure 4-30 shows the layout
of the sample-to-chunk atom. By examining the sample-to-chunk atom,
you can determine the chunk that contains a specific sample.
Figure 4-30 The layout of a sample-to-chunk atom
You define a sample-to-chunk atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this
sample-to-chunk atom.
* Type. A long integer that specifies the type of the data in this
sample-to-chunk atom (defined by the 'stsc' atom type).
* Version. A 1-byte specification of the version of this
sample-to-chunk atom.
* Flags. Three bytes of space for future flags associated with this
sample-to-chunk atom.
* Number of entries. The number of entries in the sample-to-chunk
table.
* Sample-to-chunk table. Figure 4-31 shows the structure of a
sample-to-chunk table. Each sample-to-chunk atom contains such a
table, which identifies the chunk for each sample in a media. Each
entry in the table contains a first chunk field, a samples per chunk
field, and a sample description ID field. From this information, you
can ascertain where samples reside in the media data.
Figure 4-31 The layout of a sample-to-chunk table
You define a sample-to-chunk table by specifying these elements:
* First chunk. The first chunk number using this table entry.
* Samples per chunk. The number of samples in each chunk.
* Sample description ID. The identification number associated with the
sample description containing the sample. For details on sample
description atoms, see Sample Description Atoms, which begins on page
4-35.
Figure 4-32 shows an example of a sample-to-chunk table that is based
on the data stream shown in Figure 4-22.
Figure 4-32 An example of a sample-to-chunk table
Each table entry corresponds to a set of consecutive chunks, each of
which contains the same number of samples. Furthermore, each of the
samples in these chunks must use the same sample description (see
Sample Description Atoms, which begins on page 4-35). Whenever the
number of samples per chunk or the sample description changes, you
must create a new table entry. If all the chunks have the same number
of samples per chunk and use the same sample description, this table
has one entry.
Sample Size Atoms
You use sample size atoms to identify the size of each sample in the media.
Sample size atoms have an atom type of 'stsz'. The sample size atom
(shown in Figure 4-33) contains sample size information.
Figure 4-33 The layout of a sample size atom
You define a sample size atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this
sample size atom.
* Type. A long integer that specifies the type (of atom type 'stsz') of
the data in this sample size atom.
* Version. A 1-byte specification of the version number of this sample
size atom.
* Flags. Three bytes of space for future flags associated with the data
in this sample size atom.
* Sample size. The number of bytes in the samples in the sample size
table field. If all the samples are the same size, the sample size
field of this atom indicates the size of all the samples. If this
field is set to 0, then the samples have different sizes, and those
sizes are stored in the sample size table.
* Number of entries. The number of entries in the sample size table
contained in the sample size table field of this atom.
* Sample size table. The sample size table, which contains the sample
size information. A sample size table contains an entry for every
sample.
Figure 4-34 shows the sample size table for the data stream
represented in Figure 4-22 on page 4-33.
Figure 4-34 An example of a sample size table
Chunk Offset Atoms
Chunk offset atoms identify the location of each chunk of data in the
mediaUs data stream.
Chunk offset atoms have an atom type of 'stco'. The chunk offset atom
(shown in Figure 4-35) contains a table of offset information.
Figure 4-35 The layout of a chunk offset atom
You define a chunk offset atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this chunk
offset atom.
* Type. A long integer that specifies the type of the data in this
chunk offset atom (defined by the atom type 'stco').
* Version. A 1-byte specification of the version of this chunk offset
atom.
* Flags. A 3-byte space for future flags associated with this chunk
offset atom.
* Number of entries. A long integer that specifies the number of
entries in the chunk offset table.
Chunk offset table. The chunk offset table, which consists of a
number of offset fields. Each entry in the chunk offset table
contains an offset field. There is one table entry for each
chunk in the media. The table is indexed by chunk number--
the first table entry corresponds to the first chunk, the
second table entry is for the second chunk, and so on. The offset
field contains the byte offset from the beginning of the data stream
to the chunk.
Figure 4-36 shows an example of the chunk offset table for the data
stream represented by Figure 4-22 on page 4-33.
Figure 4-36 An example of a chunk offset table
Shadow Sync Atoms
Shadow sync atoms contain self-contained samples that are alternates for
existing frame difference samples. Shadow sync atoms are used to
optimize random access operations on a movie. Scrubbing is an example
of such a random access operation. These atoms are used to enhance
playback performance. See the chapter Movie Toolbox in this book for
details on the SetMediaShadowSync and GetMediaShadowSync functions,
which allow you to create an association between a frame difference
sample and a sync sample.
Figure 4-37 shows the layout of a shadow sync atom. Shadow sync atoms
have an atom type of 'stsh'. Each shadow sync atom contains a table
with a frame difference number and a sync sample number.
Figure 4-37 The layout of a shadow sync atom
You define a shadow sync atom by specifying these elements:
* Size. A long integer that specifies the number of bytes in this
shadow sync atom.
* Type. A long integer that specifies the type (defined by the atom
type 'stsh') of the data in this shadow sync atom.
* Version. A 1-byte specification of the version number of this shadow
sync atom.
* Flags. Three bytes of space for future flags.
* Number of entries. A long integer that specifies how many entries in
the shadow sync table are listed in the shadow sync table field of
this atom.
* Shadow sync table. The shadow sync table, which contains the shadow
sync information. The shadow sync table is shown in Figure 4-38.
Figure 4-38 The layout of a shadow sync table
A shadow sync table contains a frame difference sample number and a
sync sample number.
Using Media Information Atoms
This section presents examples using the atoms just described. These
examples are intended to help you understand the relationships between
these atoms. The first example, Finding a Sample, describes the steps
that the video media handler uses to find the sample that contains the
media data for a particular time in a media. The second example,
Finding a Key Frame, describes the steps that the video media handler
uses to find an appropriate key frame for a specific time in a movie.
Finding a Sample
When it displays a movie or track, QuickTime tells the appropriate
media handler to access the media data for a particular time. The
media handler must correctly interpret the data stream to retrieve the
requested data. In the case of video media, the media handler
traverses several atoms to find the location and size of a sample for
a given media time. The media handler does the following:
1. Determines the time in the media time coordinate system.
2. Examines the time-to-sample atom to determine the sample number
that contains the data for the specified time.
3. Scans the sample-to-chunk atom to discover which chunk contains the
sample in question.
4. Extracts the offset to the chunk from the chunk offset atom.
5. Finds the offset within the chunk by using the sample size atom.
Finding a Key Frame
Finding a key frame for a specified time in a movie is slightly more
complicated than finding a sample for a specified time. The media
handler must use the sync sample atom and the time-to-sample atom
together in order to find a key frame. The media handler does the
following:
1. Examines the time-to-sample atom to determine the sample number
that contains the data for the specified time.
2. Scans the sync sample atom to find the key frame that precedes the
sample number chosen in step 1.
3. Scans the sample-to-chunk atom to discover which chunk contains the
key frame.
4. Extracts the offset to the chunk from the chunk offset atom.
5. Finds the offset within the chunk by using the sample size atom.
This chapter has described the format of QuickTime movie resources for
those developers who need to know about the content of movie
resources. The knowledge you have gained about movie resources should
help you in the creation of movies on other computers and in the
process of importing them to the Macintosh environment, or in the
interpretation of QuickTime movies on other types of computers.
