PDF Reference sixth edition, Adobe Portable Document Format Version 1.7 (book 2) — page 5
763
SECTION 9.1
Multimedia
KEY
TYPE
VALUE
SP
dictionary
(Optional) A media screen parameters dictionary (see Section 9.1.5, “Media Screen
Parameters”) that specifies where the media rendition object should be played.
Default value: a media screen parameters dictionary whose entries (see Table 9.17)
all contain their default values.
Selector Renditions
A selector rendition dictionary specifies an array of rendition objects in its R entry
(see Table 9.7). The renditions in this array should be ordered by preference, with
the most preferred rendition first. At play-time, the renditions in the array are
evaluated and the first viable media rendition, if any, is played. If one of the rendi-
tions is itself a selector, that selector is evaluated in turn, yielding the equivalent
of a depth-first tree search. Note, however, that a selector rendition itself may be
non-viable; in this case, none of its associated media renditions are evaluated (in
effect, this branch of the tree is skipped).
This mechanism may be used, for example, to specify that a large video clip
should be used on high-bandwidth machines and a smaller clip should be used
on low-bandwidth machines.
TABLE 9.7 Additional entries specific to a selector rendition dictionary
KEY
TYPE
VALUE
R
array
(Required) An array of rendition objects. The first viable media rendition object
found in the array, or nested within a selector rendition in the array, should be used.
An empty array is legal.
9.1.3
Media Clip Objects
There are two types of media clip objects, determined by the subtype S, which
can be either MCD for media clip data (see “Media Clip Data” on page 764) or
MCS for media clip section (see “Media Clip Section” on page 767). The entries
common to all media clip dictionaries are listed in Table 9.8.
764
CHAPTER 9
Multimedia Features
TABLE 9.8 Entries common to all media clip dictionaries
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
MediaClip for a media clip dictionary.
S
name
(Required) The subtype of media clip that this dictionary describes. May be MCD for
media clip data (see “Media Clip Data” on page 764) or MCS for a media clip section
(see “Media Clip Section” on page 767). The media clip is considered non-viable if
the viewer application does not recognize the value of this entry.
N
text string
(Optional) The name of the media clip, for use in the user interface.
Media Clip Data
A media clip data dictionary defines the data for a media object that can be
played. For example, it may reference a URL to a streaming video presentation or
a movie embedded in the PDF file. Its entries are listed in Table 9.9.
TABLE 9.9 Additional entries in a media clip data dictionary
KEY
TYPE
VALUE
D
file specification
(Required) A full file specification or form XObject that specifies the actual media
or stream
data.
CT
ASCII string
(Optional; not allowed for form XObjects) An ASCII string identifying the type of
data in D. The string should conform to the content type specification described in
Internet RFC 2045, Multipurpose Internet Mail Extensions (MIME) Part One: For-
mat of Internet Message Bodies (see the Bibliography).
P
dictionary
(Optional) A media permissions dictionary (see Table 9.10) containing permissions
that control the use of the media data. Default value: a media permissions dictio-
nary containing default values.
Alt
array
(Optional) An array that provides alternate text descriptions for the media clip data
in case it cannot be played; see “Multi-language Text Arrays” on page 942.
PL
dictionary
(Optional) A media players dictionary (see “Media Players Dictionary” on page 777)
that identifies, among other things, players that are legal and not legal for playing
the media.
Note: If the media players dictionary is non-viable, the media clip data is non-viable.
765
SECTION 9.1
Multimedia
KEY
TYPE
VALUE
MH
dictionary
(Optional) A dictionary whose entries (see Table 9.11) must be honored for the me-
dia clip data to be considered viable.
BE
dictionary
(Optional) A dictionary whose entries (see Table 9.11) need only be honored in a
“best effort” sense.
The media clip data object must be considered non-viable if the object referenced
by the D entry does not contain a Type entry, the Type entry is unrecognized, or
the referenced object is not a dictionary or stream. Note that this excludes the use
of simple file specifications (see Section 3.10, “File Specifications”).
If D references a file specification that has an embedded file stream (see Section
3.10.3, “Embedded File Streams”), the embedded file stream’s Subtype entry is ig-
nored if present, and the media clip data dictionary’s CT entry identifies the type
of data.
If D references a form XObject, the associated player is implicitly the viewer ap-
plication, and the form XObject should be rendered as if it were any other data
type. For example, the F and D entries in the media play parameters dictionary
(see Table 9.14) apply to a form XObject just as they do to a QuickTime movie.
For media other than form XObjects, the media clip object must provide enough
information to allow a viewer application to locate an appropriate player. This can
be done by providing one or both of the following entries:
• A CT entry that specifies the content type of the media (the preferred method).
If this entry is present, any player that is selected must support this content
type.
• A PL entry that specifies one or more players that can be used to play the refer-
enced media. It is highly recommended if CT is present. However, see imple-
mentation note 149 in Appendix H.
The P entry specifies a media permissions dictionary (see Table 9.10) specifying
the manner in which the data referenced by the media may be used by a viewer
application. These permissions allow authors control over how their data is ex-
posed to operations that could allow it to be copied. If the dictionary contains un-
recognized entries or entries with unrecognized values, it should be considered
non-viable, and the viewer application should not play the media.
766
CHAPTER 9
Multimedia Features
TABLE 9.10 Entries in a media permissions dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
MediaPermissions for a media permissions dictionary.
TF
ASCII
(Optional) An ASCII string indicating the circumstances under which it is accept-
string
able to write a temporary file in order to play a media clip. Valid values are:
(TEMPNEVER)
Never allowed.
(TEMPEXTRACT) Allowed only if the document permissions allow content
extraction; for example, when bit
5 of the user access
permissions (see Table 3.20) is set.
(TEMPACCESS) Allowed only if the document permissions allow content
extraction, including for accessibility purposes; for example,
when bits 5 or 10 of the user access permissions (see Table
3.20) are set, or both.
(TEMPALWAYS) Always allowed.
Default value: (TEMPNEVER).
An unrecognized value is treated as (TEMPNEVER).
The BU entry in the media clip data MH and BE dictionaries (see Table 9.11) spec-
ifies a base URL for the media data. Relative URLs in the media (which point to
auxiliary files or are used for hyperlinking, for example) should be resolved with
respect to the value of BU. The following should be noted about the BU entry:
• If BU is in the MH dictionary and the base URL is not honored (for example, the
player does not accept base URLs), the media clip data is non-viable.
• Determining the viability of the object does not require checking whether the
base URL is valid (for example, that the target host exists).
• Absolute URls within the media are not affected.
• If the media itself contains a base URL (for example, the <BASE> element is de-
fined in HTML), that value is used in preference to BU.
• BU is completely independent of and unrelated to the value of the URI entry in
the document catalog (see Section 3.6.1, “Document Catalog”).
767
SECTION 9.1
Multimedia
• If BU is not present and the media is embedded within the document, the URL
to the PDF file itself should be used as if it were the value of a BU entry in the BE
dictionary; that is, as an implicit best-effort base URL.
TABLE 9.11 Entries in a media clip data MH/BE dictionary
KEY
TYPE
VALUE
BU
ASCII
(Optional) An absolute URL to be used as the base URL in resolving any relative
string
URLs found within the media data.
Media Clip Section
A media clip section dictionary (see Table 9.12) defines a continuous section of
another media clip object (known as the next-level media clip object). For exam-
ple, a media clip section could define a 15-minute segment of a media clip data
object representing a two-hour movie. The next-level media clip object, specified
by the D entry, can be either a media clip data object or another media clip sec-
tion object. However, the linked list formed by the D entries of media clip sec-
tions must terminate in a media clip data object. If the next-level media object is
non-viable, the media clip section is also non-viable.
TABLE 9.12 Additional entries in a media clip section dictionary
KEY
TYPE
VALUE
D
dictionary
(Required) The media clip section or media clip data object (the next-level media
object) of which this media clip section object defines a continuous section.
Alt
array
(Optional) An array that provides alternate text descriptions for the media clip sec-
tion in case it cannot be played; see “Multi-language Text Arrays” on page 942.
MH
dictionary
(Optional) A dictionary whose entries (see Table 9.13) must be honored for the me-
dia clip section to be considered viable.
BE
dictionary
(Optional) A dictionary whose entries (see Table 9.13) need only be honored in a
“best effort” sense.
The B and E entries in the media clip section’s MH and BE dictionaries (see Table
9.13) define a subsection of the next-level media object referenced by D by speci-
fying beginning and ending offsets into it. Depending on the media type, the off-
sets may be specified by time, frames, or markers (see “Media Offset Dictionary”
on page 775). B and E are not required to specify the same type of offset.
768
CHAPTER 9
Multimedia Features
The following rules apply to these offsets:
• For media types where an offset makes no sense (such as JPEG images), B and E
are ignored, with no effect on viability.
• When B or E are specified by time or frames, their value is considered to be rel-
ative to the start of the next-level media clip. However, if E specifies an offset
beyond the end of the next-level media clip, the end value is used instead, and
there is no effect on viability.
• When B or E are specified by markers, there is a corresponding absolute offset
into the underlying media clip data object. If this offset is not within the range
defined by the next-level media clip (if any), or if the marker is not present in
the underlying media clip, the existence of the entry is ignored, and there is no
effect on viability.
• If the absolute offset derived from the values of all B entries in a media clip sec-
tion chain is greater than or equal to the absolute offset derived from the values
of all E entries, an empty range is defined. An empty range is legal.
• Any B or E entry in a media clip section’s MH dictionary must be honored at
play-time in order for the media clip section to be considered viable. (The entry
might not be honored if its value was not viable or if the player did not support
its value; for example, the player did not support markers.)
• If a B or E entry is in a media clip section’s MH dictionary, all B or E entries, re-
spectively, at deeper levels (closer to the media clip data), are evaluated as if
they were in an MH dictionary (even if they are actually within BE dictionaries).
• If B or E entry in a BE dictionary cannot be supported, it may be ignored at
play-time.
TABLE 9.13 Entries in a media clip section MH/BE dictionary
KEY
TYPE
VALUE
B
dictionary
(Optional) A media offset dictionary (see “Media Offset Dictionary” on page 775)
that specifies the offset into the next-level media object at which the media clip sec-
tion begins. Default: the start of the next-level media object.
E
dictionary
(Optional) A media offset dictionary (see “Media Offset Dictionary” on page 775)
that specifies the offset into the next-level media object at which the media clip sec-
tion ends. Default: the end of the next-level media object.
769
SECTION 9.1
Multimedia
9.1.4
Media Play Parameters
A media play parameters dictionary specifies how a media object should be
played. It is referenced from a media rendition (see “Media Renditions” on page
762).
TABLE 9.14 Entries in a media play parameters dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
MediaPlayParams for a media play parameters dictionary.
PL
dictionary
(Optional) A media players dictionary (see “Media Players Dictionary” on page
777) that identifies, among other things, players that are legal and not legal for play-
ing the media.
Note: If this object is non-viable, the media play parameters dictionary is considered
non-viable.
MH
dictionary
(Optional) A dictionary whose entries (see Table 9.13) must be honored for the me-
dia play parameters to be considered viable.
BE
dictionary
(Optional) A dictionary whose entries (see Table 9.13) need only be honored in a
“best effort” sense.
TABLE 9.15 Entries in a media play parameters MH/BE dictionary
KEY
TYPE
VALUE
V
integer
(Optional) An integer that specifies the desired volume level as a percentage of re-
corded volume level. A zero value is equivalent to mute; negative values are illegal.
Default value: 100.
C
boolean
(Optional) A flag specifying whether to display a player-specific controller user in-
terface (for example, play/pause/stop controls) when playing. Default value: false
770
CHAPTER 9
Multimedia Features
KEY
TYPE
VALUE
F
integer‘
(Optional) The manner in which the player should treat a visual media type that
does not exactly fit the rectangle in which it plays.
0
The media’s width and height are scaled while preserving the aspect ratio
so that the media and play rectangles have the greatest possible
intersection while still displaying all media content. Same as “meet” value
of SMIL’s fit attribute.
1
The media’s width and height are scaled while preserving the aspect ratio
so that the play rectangle is entirely filled, and the amount of media
content that does not fit within the play rectangle is minimized. Same as
“slice” value of SMIL’s fit attribute.
2
The media’s width and height are scaled independently so that the media
and play rectangles are the same; the aspect ratio is not necessarily
preserved. Same as “fill” value of SMIL’s fit attribute.
3
The media is not scaled. A scrolling user interface is provided if the media
rectangle is wider or taller than the play rectangle. Same as “scroll” value
of SMIL’s fit attribute.
4
The media is not scaled. Only the portions of the media rectangle that
intersect the play rectangle are displayed. Same as “hidden” value of
SMIL’s fit attribute.
5
Use the player’s default setting (author has no preference).
Default value: 5.
An unrecognized value should be treated as the default value if the entry is in a BE
dictionary. If the entry is in an MH dictionary and it has an unrecognized value, the
object should be considered non-viable.
D
dictionary
(Optional) A media duration dictionary (see Table 9.16). Default value: a dictionary
specifying the intrinsic duration (see below).
A
boolean
(Optional) If true, the media should automatically play when activated. If false, the
media should be initially paused when activated (for example, the first frame is dis-
played). Relevant only for media that may be paused. Default value: true.
RC
number
(Optional) Specifies the number of iterations of the duration D to repeat; similar to
SMIL’s repeatCount attribute. Zero means repeat forever. Negative values are illegal;
non-integral values are legal. Default value: 1.0.
The value of the D entry is a media duration dictionary, whose entries are shown
in Table 9.16. It specifies a temporal duration (which corresponds to the notion of
a simple duration in SMIL). The duration may be a specific amount of time, it
may be infinity, or it may be the media’s intrinsic duration (for example, the in-
trinsic duration of a two-hour QuickTime movie is two hours). The intrinsic du-
771
SECTION 9.1
Multimedia
ration may be modified when a media clip section (see “Media Clip Section” on
page 767) is used: the intrinsic duration is the difference between the absolute be-
gin and end offsets. For a media type having no notion of time (such as a JPEG
image), the duration is considered to be infinity.
If the simple duration is longer than the intrinsic duration, the player should
freeze the media in its final state until the simple duration has elapsed. For visual
media types, the last appearance (frame) would be displayed. For aural media
types, the media is logically frozen but should not continue to produce sound.
Note: In this case, the RC entry, which specifies a repeat count, applies to the simple
duration; therefore, the entire play-pause sequence is repeated RC times.
TABLE 9.16 Entries in a media duration dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
MediaDuration for a media duration dictionary.
S
name
(Required) The subtype of media duration dictionary. Valid values are:
I
The duration is the intrinsic duration of the associated media
F
The duration is infinity
T
The duration is specified by the T entry
The media duration dictionary is considered non-viable if the viewer application
does not recognize the value of this entry.
T
dictionary
(Required if the value of S is T; otherwise ignored) A timespan dictionary specifying
an explicit duration (see Table 9.24). A negative duration is illegal.
9.1.5
Media Screen Parameters
A media screen parameters dictionary (see Table 9.17) specifies where a media
object should be played. It contains MH and BE dictionaries (see Table 9.18),
which function as discussed in Section 9.1.1, “Viability.” All media clips that are
being played are associated with a particular document and must be stopped
when the document is closed.
Note: It is recommended that viewer applications disallow floating windows and
full-screen windows unless specifically allowed by the user. The reason is that docu-
ment-based security attacks are possible if windows containing arbitrary media con-
tent can be displayed without indicating to the user that the window is merely
772
CHAPTER 9
Multimedia Features
hosting a media object. This recommendation may be relaxed if it is possible to com-
municate the nature of such windows to the user; for example, with text in a float-
ing window’s title bar.
TABLE 9.17 Entries in a media screen parameters dictionary
KEY
TYPE
VALUE
Type name
(Optional) The type of PDF object that this dictionary describes; if present, must be
MediaScreenParams for a media screen parameters dictionary.
MH dictionary
(Optional) A dictionary whose entries (see Table 9.18) must be honored for the me-
dia screen parameters to be considered viable.
BE
dictionary
(Optional) A dictionary whose entries (see Table 9.18) need only be honored in a
“best effort” sense.
TABLE 9.18 Entries in a media screen parameters MH/BE dictionary
KEY
TYPE
VALUE
W
integer
(Optional) The type of window that the media object should play in:
0
A floating window
1
A full-screen window that obscures all other windows
2
A hidden window
3
The rectangle occupied by the screen annotation (see “Screen
Annotations” on page 639) associated with the media rendition
Default value: 3. Unrecognized value in MH: object is non-viable; in BE: treat as de-
fault value.
B
array
(Optional) An array of three numbers in the range 0.0 to 1.0 specifying the compo-
nents in the DeviceRGB color space of the background color for the rectangle in
which the media is being played. This color is used if the media object does not en-
tirely cover the rectangle or if it has transparent sections. Ignored for hidden win-
dows.
Default value: implementation-defined. The viewer application should choose a
reasonable value based on the value of W; for example, a system default background
color for floating windows or a user-preferred background color for full-screen
windows.
Note: If a media format has an intrinsic background color, B does not override it.
However, the B color is visible if the media has transparent areas or otherwise does not
cover the entire window.
773
SECTION 9.1
Multimedia
KEY
TYPE
VALUE
O
number
(Optional) A number in the range 0.0 to 1.0 specifying the constant opacity value to
be used in painting the background color specified by B. A value below 1.0 means
the window is transparent; for example, windows behind a floating window show
through if the media does not cover the entire floating window. A value of 0.0 indi-
cates full transparency and makes B irrelevant. Ignored for full-screen and hidden
windows.
Default value: 1.0 (fully opaque).
M
integer
(Optional) A monitor specifier (see Table 9.28) that specifies which monitor in a
multi-monitor system a floating or full-screen window should appear on. Ignored
for other types.
Default value: 0 (document monitor). Unrecognized value in MH: object is non-via-
ble; in BE: treat as default value.
F
dictionary
(Required if the value of W is 0; otherwise ignored) A floating window parameters
dictionary (see Table 9.19) specifying the size, position, and options used in dis-
playing floating windows.
The F entry in the media screen parameters MH/BE dictionaries is a floating win-
dow parameters dictionary, whose entries are listed in Table 9.19. The entries in
the floating window parameters dictionary are treated as if they were present in
the MH or BE dictionaries that they are referenced from. That is, the contained
entries are individually evaluated for viability rather than the dictionary being
evaluated as a whole. (There may be an F entry in both MH and BE. In such a case,
if a given entry is present in both floating window parameters dictionaries, the
one in the MH dictionary takes precedence.)
The D, P, and RT entries are used to specify the rectangle that the floating window
occupies. Once created, the floating window’s size and position are not tied to any
other window, even if the initial size or position was computed relative to other
windows.
Unrecognized values for the R, P, RT, and O entries are handled as follows: if they
are nested within an MH dictionary, the floating window parameters object (and
hence the media screen parameters object) must be considered non-viable; if they
are nested within a BE dictionary, they should be considered to have their default
values.
774
CHAPTER 9
Multimedia Features
TABLE 9.19 Entries in a floating window parameters dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
FWParams for a floating window parameters dictionary.
D
array
(Required) An array containing two non-negative integers representing the floating
window’s width and height, in pixels, respectively. These values correspond to the
dimensions of the rectangle in which the media will play, not including such items
as title bar and resizing handles.
RT
integer
(Optional) The window relative to which the floating window should be positioned:
0
The document window
1
The application window
2
The full virtual desktop
3
The monitor specified by M in the media screen parameters MH or
BE dictionary (see 9.22)
Default value: 0.
P
integer
(Optional) The location where the floating window (including such items as title
bar and resizing handles) should be positioned relative to the window specified by
RT:
0
Upper-left corner
1
Upper center
2
Upper-right corner
3
Center left
4
Center
5
Center right
6
Lower-left corner
7
Lower center
8
Lower-right corner
Default value: 4.
O
integer
(Optional) Specifies what should occur if the floating window is positioned totally
or partially offscreen (that is, not visible on any physical monitor):
0
Take no special action
1
Move and/or resize the window so that it is on-screen
2
Consider the object to be non-viable
Default value: 1
T
boolean
(Optional) If true, the floating window should have a title bar. Default value: true.
775
SECTION 9.1
Multimedia
KEY
TYPE
VALUE
UC
boolean
(Optional; meaningful only if T is true) If true, the floating window should include
user interface elements that allow a user to close a floating window.
Default value: true
R
integer
(Optional) Specifies whether the floating window may be resized by a user:
0
May not be resized
1
May be resized only if aspect ratio is preserved
2
May be resized without preserving aspect ratio
Default value: 0.
TT
array
(Optional; meaningful only if T is true) An array providing text to display on the
floating window’s title bar. See “Multi-language Text Arrays” on page 942. If this en-
try is not present, the viewer application may provide default text.
Media Offset Dictionary
A media offset dictionary (Table 9.20) specifies an offset into a media object. The
S (subtype) entry indicates how the offset is specified: in terms of time (for exam-
ple, “10 seconds”), frames (for example, “frame 20”) or markers (for example,
“Chapter One”). Different media types support different types of offsets.
TABLE 9.20 Entries common to all media offset dictionaries
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
MediaOffset for a media offset dictionary.
S
name
(Required) The subtype of media offset dictionary. Valid values are:
T
A media offset time dictionary (see Table 9.21)
F
A media offset frame dictionary (see Table 9.22)
M
A media offset marker dictionary (see Table 9.23)
The rendition is considered non-viable if the viewer application does not recognize
the value of this entry.
776
CHAPTER 9
Multimedia Features
TABLE 9.21 Additional entries in a media offset time dictionary
KEY
TYPE
VALUE
T
dictionary
(Required) A timespan dictionary (see Table 9.24) that specifies a temporal offset
into a media object. Negative timespans are not allowed in this context. The media
offset time dictionary is non-viable if its timespan dictionary is non-viable.
TABLE 9.22 Additional entries in a media offset frame dictionary
KEY
TYPE
VALUE
F
integer
(Required) Specifies a frame within a media object. Frame numbers begin at 0; neg-
ative frame numbers are not allowed.
TABLE 9.23 Additional entries in a media offset marker dictionary
KEY
TYPE
VALUE
M
text string
(Required) A text string that identifies a named offset within a media object.
Timespan Dictionary
A timespan dictionary specifies a length of time; its entries are shown in Table
9.24.
TABLE 9.24 Entries in a timespan dictionary
KEY
TYPE
VALUE
Type name
(Optional) The type of PDF object that this dictionary describes; if present, must be
Timespan for a timespan dictionary.
S
name
(Required) The subtype of timespan dictionary. The only value currently allowed is
S (simple timespan). The rendition is considered non-viable if the viewer applica-
tion does not recognize the value of this entry.
V
number
(Required) The number of seconds in the timespan. Non-integral values are al-
lowed. Negative values are allowed, but may be disallowed in some contexts (all sit-
uations defined in PDF 1.5 disallow negative values).
Note: This entry is required only if the value of the S entry is S. Subtypes defined in the
future need not use this entry.
777
SECTION 9.1
Multimedia
9.1.6
Other Multimedia Objects
This section defines several dictionary types that are referenced by the previous
sections.
Media Players Dictionary
A media players dictionary can be referenced by media clip data (see “Media Clip
Data” on page 764) and media play parameters (see Section 9.1.4, “Media Play Pa-
rameters”) dictionaries, and allows them to specify which players may or may not
be used to play the associated media. The media players dictionary references
media player info dictionaries (see “Media Player Info Dictionary,” below) that
provide specific information about each player.
TABLE 9.25 Entries in a media players dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
MediaPlayers for a media players dictionary.
MU
array
(Optional) An array of media player info objects (see Table 9.26) that specify a set of
players, one of which must be used in playing the associated media object.
Note: Any players specified in NU are effectively removed from MU. (For example, if
MU specifies versions 1 through 5 of a player and NU specifies versions 1 and 2 of the
same player, MU is effectively versions 3 through 5.)
A
array
(Optional) An array of media player info objects (see Table 9.26) that specify a set of
players, any of which may be used in playing the associated media object. If MU is
also present and non-empty, A is ignored.
NU
array
(Optional) An array of media player info objects (see Table 9.26) that specify a set of
players that must not be used in playing the associated media object (even if they are
also specified in MU).
The MU, A, and NU entries each specify one or more media player info objects.
(An empty array is treated as if it is not present.) The media player info objects
are allowed to specify overlapping player ranges (for example, MU could contain a
media player info dictionary describing versions 1 to 10 of Player X and another
describing versions 3 through 5 of Player X).
778
CHAPTER 9
Multimedia Features
If a non-viable media player info object is referenced by MU, NU, or A, it is treated
as if it were not present in its original array, and a media player info object con-
taining the same software identifier dictionary (see “Software Identifier Dictio-
nary” on page 779) is logically considered to be present in NU. The same rule
applies to a media player info object that contains a partially unrecognized soft-
ware identifier dictionary.
Since both media clip data and media play parameters dictionaries can be em-
ployed in a play operation, and each can reference a media players dictionary,
there is a potential for conflict between the contents of the two media players dic-
tionaries. At play-time, the viewer should use the following algorithm to deter-
mine whether a player present on the machine can be employed. The player
cannot be used if any of the following conditions are true:
Algorithm 9.1
1.
The content type is known and the player does not support the type.
2.
The player is found in the NU array of either dictionary.
3.
Both dictionaries have non-empty MU arrays and the player is not found in both
of them, or only one of the dictionaries has a non-empty MU array and the player
is not found in it.
4.
Neither dictionary has a non-empty MU array, the content type is not known, and
the player is not found in the A array of either dictionary.
If none of the conditions are true, the player can be used.
Note: A player is “found” in the NU, MU, or A arrays if it matches the information
found in the PID entry of one of the entries, as described by Algorithm 9.2.
Media Player Info Dictionary
A media player info dictionary provides a variety of information regarding a spe-
cific media player. Its entries (see Table 9.26) allow information to be associated
with a particular version or range of versions of a player. As of PDF 1.5, only the
PID entry provides information about the player, as described in the next section,
“Software Identifier Dictionary”.
779
SECTION 9.1
Multimedia
TABLE 9.26 Entries in a media player info dictionary
KEY
TYPE
VALUE
Type name
(Optional) The type of PDF object that this dictionary describes; if present, must be
MediaPlayerInfo for a media player info dictionary.
PID
dictionary
(Required) A software identifier object (see “Software Identifier Dictionary,” below)
that specifies the player name, versions, and operating systems to which this media
player info object applies.
MH dictionary
(Optional) A dictionary containing entries that must be honored for this object to
be considered viable
Note: Currently, there are no defined entries for this dictionary
BE
dictionary
(Optional) A dictionary containing entries that need only be honored in a “best ef-
fort” sense.
Note: Currently, there are no defined entries for this dictionary
Software Identifier Dictionary
A software identifier dictionary allows software to be identified by name, range of
versions, and operating systems; its entries are listed in Table 9.27. A viewer ap-
plication uses this information to determine whether a given media player can be
used in a given situation. If the dictionary contains keys that are unrecognized by
the viewer application, it is considered to be partially recognized. The viewer ap-
plication may or may not decide to treat the software identifier as viable, depend-
ing on the context in which it is used.
The following procedure is used to determine whether a piece of software is con-
sidered to match a software identifier object:
Algorithm 9.2
1.
The software name must match the name specified by the U entry (see “Software
URIs,” below).
2.
The software version must be within the interval specified by the L, H, LI, and H1
entries (see “Version arrays,” below).
3.
The machine’s operating system name must be an exact match for one present in
the OS array. If the array is not present or empty, a match is also considered to ex-
ist.
780
CHAPTER 9
Multimedia Features
TABLE 9.27 Entries in a software identifier dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
SoftwareIdentifier for a software identifier dictionary.
U
ASCII string
(Required) A URI that identifies a piece of software (see “Software URIs,” below).
L
array
(Optional) The lower bound of the range of software versions that this software
identifier object specifies (see “Version arrays,” below). Default value: the array [0].
LI
boolean
(Optional) If true, the lower bound of the interval defined by L and H is inclusive;
that is, the software version must be greater than or equal to L (see “Version arrays,”
below). If false, it is not inclusive. Default value: true.
H
array
(Optional) The upper bound of the range of software versions that this software
identifier object specifies (see “Version arrays,” below). Default value: an empty ar-
ray [].
HI
boolean
(Optional) If true, the upper bound of the interval defined by L and H is inclusive;
that is, the software version must be less than or equal to H (see “Version arrays,” be-
low). If false, it is not inclusive. Default value: true.
OS
array
(Optional) An array of byte strings representing operating system identifiers that
indicate which operating systems this object applies to. The defined values are the
same as those defined for SMIL 2.0’s systemOperatingSystem attribute. There may
not be multiple copies of the same identifier in the array. An empty array is consid-
ered to represent all operating systems. Default value: an empty array.
Software URIs
The U entry is a URI (universal resource identifier) that identifies a piece of soft-
ware. It is interpreted according to its scheme; the only presently defined scheme
is vnd.adobe.swname. The scheme name is case-insensitive; if is not recognized by
the viewer application, the software must be considered a non-match. The syntax
of URIs of this scheme is
“vnd.adobe.swname:” software_name
where software_name is equivalent to reg_name as defined in Internet RFC 2396,
Uniform Resource Identifiers
(URI): Generic Syntax; see the Bibliography.
software_name is considered to be a sequence of UTF-8-encoded characters that
have been escaped with one pass of URL escaping (see “URL Strings” on page
781
SECTION 9.1
Multimedia
950). That is, to recover the original software name, software_name must be unes-
caped and then treated as a sequence of UTF-8 characters. The actual software
names must be compared in a case-sensitive fashion.
Software names are second-class names (see Appendix E). For example, the URI
for Acrobat is
vnd.adobe.swname:ADBE_Acrobat
Version arrays
The L, H, LI, and HI entries are used to specify a range of software versions. L and
H are version arrays containing zero or more non-negative integers representing
subversion numbers. The first integer is the major version numbers, and subse-
quent integers are increasingly minor. H must be greater than or equal to L, ac-
cording to the following rules for comparing version arrays:
Algorithm 9.3 Comparing version arrays
1.
An empty version array is treated as infinity; that is, it is considered greater than
any other version array except another empty array. Two empty arrays are equal.
2.
When comparing arrays that contain different numbers of elements, the smaller
array is implicitly padded with zero-valued integers to make the number of ele-
ments equal. For example, when comparing [5 1 2 3 4] to [5], the latter is treated as
[5 0 0 0 0].
3.
The corresponding elements of the arrays are compared, starting with the first.
When a difference is found, the array containing the larger element is considered
to have the larger version number. If no differences are found, the versions are
equal.
Note: If a version array contains negative numbers, it is considered non-viable, as
is the enclosing software identifier.
Monitor Specifier
A monitor specifier is an integer that identifies a physical monitor attached to a
system. It can have one of the values in Table 9.28:
782
CHAPTER 9
Multimedia Features
TABLE 9.28 Monitor specifier values
VALUE
DESCRIPTION
0
The monitor containing the largest section of the document window
1
The monitor containing the smallest section of the document window
2
Primary monitor. If no monitor is considered primary, use case 0
3
Monitor with the greatest color depth
4
Monitor with the greatest area (in pixels squared)
5
Monitor with the greatest height (in pixels)
6
Monitor with the greatest width (in pixels)
For some of these values, it is possible have a “tie” at play-time; for example, two
monitors might have the same color depth. Ties are broken in an implementa-
tion-dependent manner.
9.2
Sounds
A sound object (PDF 1.2) is a stream containing sample values that define a sound
to be played through the computer’s speakers. The Sound entry in a sound anno-
tation or sound action dictionary (see Table 8.36 on page 638 and Table 8.58 on
page 664) identifies a sound object representing the sound to be played when the
annotation is activated.
Since a sound object is a stream, it can contain any of the standard entries com-
mon to all streams, as described in Table 3.4 on page 62. In particular, if it con-
tains an F (file specification) entry, the sound is defined in an external file. This
sound file must be self-describing, containing all information needed to render
the sound; no additional information need be present in the PDF file.
Note: The AIFF, AIFF-C (Mac OS), RIFF (. wav), and snd (. au) file formats are all
self-describing.
If no F entry is present, the sound object itself contains the sample data and all
other information needed to define the sound. Table 9.29 shows the additional
dictionary entries specific to a sound object.
783
SECTION 9.2
Sounds
TABLE 9.29 Additional entries specific to a sound object
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present, must be
Sound for a sound object.
R
number
(Required) The sampling rate, in samples per second.
C
integer
(Optional) The number of sound channels. Default value: 1. (See implementation
note 150 in Appendix H.)
B
integer
(Optional) The number of bits per sample value per channel. Default value: 8.
E
name
(Optional) The encoding format for the sample data:
Raw
Unspecified or unsigned values in the range 0 to 2B − 1
Signed
Twos-complement values
muLaw
μ-law-encoded samples
ALaw
A-law-encoded samples
Default value: Raw.
CO
name
(Optional) The sound compression format used on the sample data. (This is separate
from any stream compression specified by the sound object’s Filter entry; see Table
3.4 on page 62 and Section 3.3, “Filters.”) If this entry is absent, no sound compres-
sion has been used; the data contains sampled waveforms to be played at R samples
per second per channel.
CP
(various)
(Optional) Optional parameters specific to the sound compression format used.
Note: At the time of publication, no standard values have been defined for the CO and
CP entries.
Sample values are stored in the stream with the most significant bits first (big-en-
dian order for samples larger than 8 bits). Samples that are not a multiple of 8 bits
are packed into consecutive bytes, starting at the most significant end. If a sample
extends across a byte boundary, the most significant bits are placed in the first
byte, followed by less significant bits in subsequent bytes. For dual-channel ste-
reophonic sounds, the samples are stored in an interleaved format, with each
sample value for the left channel (channel 1) preceding the corresponding sample
for the right (channel 2).
To maximize the portability of PDF documents containing embedded sounds, it
is recommended that PDF viewer applications and plug-in extensions support at
784
CHAPTER 9
Multimedia Features
least the following formats (assuming the platform has sufficient hardware and
OS support to play sounds at all):
R
8000, 11,025, or 22,050 samples per second
C
1 or 2 channels
B
8 or 16 bits per channel
E
Raw, Signed, or muLaw encoding
If the encoding (E) is Raw or Signed, R must be 11,025 or 22,050 samples per
channel. If the encoding is muLaw, R must be 8000 samples per channel, C must
be 1 channel, and B must be 8 bits per channel. Sound players should be prepared
to convert between formats, downsample rates, and combine channels as neces-
sary to render sound on the target platform.
9.3
Movies
Note: The features described in this section are obsolescent and their use is no longer
recommended. They are superseded by the general multimedia framework described
in Section 9.1, “Multimedia.”
PDF includes the ability to embed movies within a document by means of movie
annotations (see “Movie Annotations” on page 639). Despite the name, a movie
may consist entirely of sound with no visible images to be displayed on the
screen. The Movie and A (activation) entries in the movie annotation dictionary
refer, respectively, to a movie dictionary (Table 9.30) describing the static charac-
teristics of the movie and a movie activation dictionary (Table 9.31) specifying
how it should be presented.
TABLE 9.30 Entries in a movie dictionary
KEY
TYPE
VALUE
F
file specification
(Required) A file specification identifying a self-describing movie file.
Note: The format of a self-describing movie file is left unspecified, and there is
no guarantee of portability.
Aspect
array
(Optional) The width and height of the movie’s bounding box, in pixels, spec-
ified as [ width height ]. This entry should be omitted for a movie consisting
entirely of sound with no visible images. See implementation note 151 in Ap-
pendix H.
785
SECTION 9.3
Movies
KEY
TYPE
VALUE
Rotate
integer
(Optional) The number of degrees by which the movie is rotated clockwise
relative to the page. The value must be a multiple of 90. Default value: 0.
Poster
boolean or stream
(Optional) A flag or stream specifying whether and how to display a poster
image representing the movie. If this value is a stream, it contains an image
XObject (see Section 4.8, “Images”) to be displayed as the poster. If it is the
boolean value true, the poster image should be retrieved from the movie file;
if it is false, no poster should be displayed. See implementation note 152 in
Appendix H. Default value: false.
TABLE 9.31 Entries in a movie activation dictionary
KEY
TYPE
VALUE
Start
(various)
(Optional) The starting time of the movie segment to be played. Movie time
values are expressed in units of time based on a time scale, which defines the
number of units per second. The default time scale is defined in the movie
data. The starting time is nominally a non-negative 64-bit integer, specified
as follows:
• If it is representable as an integer (subject to the implementation limit for
integers, as described in Appendix C), it should be specified as such.
• If it is not representable as an integer, it should be specified as an 8-byte
string representing a 64-bit twos-complement integer, most significant
byte first.
• If it is expressed in a time scale different from that of the movie itself, it is
represented as an array of two values: an integer or byte string denoting the
starting time, as above, followed by an integer specifying the time scale in
units per second.
If this entry is omitted, the movie is played from the beginning.
Duration
(various)
(Optional) The duration of the movie segment to be played, specified in the
same form as Start. If this entry is omitted, the movie is played to the end.
Rate
number
(Optional) The initial speed at which to play the movie. If the value of this en-
try is negative, the movie is played backward with respect to Start and
Duration. Default value: 1.0.
Volume
number
(Optional) The initial sound volume at which to play the movie, in the range
−1.0 to 1.0. Higher values denote greater volume; negative values mute the
sound. Default value: 1.0.
786
CHAPTER 9
Multimedia Features
KEY
TYPE
VALUE
ShowControls
boolean
(Optional) A flag specifying whether to display a movie controller bar while
playing the movie. Default value: false.
Mode
name
(Optional) The play mode for playing the movie:
Once
Play once and stop.
Open
Play and leave the movie controller bar open.
Repeat
Play repeatedly from beginning to end until stopped.
Palindrome Play continuously forward and backward until stopped.
Default value: Once.
Synchronous
boolean
(Optional) A flag specifying whether to play the movie synchronously or
asynchronously. If this value is true, the movie player retains control until the
movie is completed or dismissed by the user. If the value is false, the player
returns control to the viewer application immediately after starting the mov-
ie. Default value: false.
FWScale
array
(Optional) The magnification (zoom) factor at which to play the movie. The
presence of this entry implies that the movie is to be played in a floating win-
dow. If the entry is absent, the movie is played in the annotation rectangle.
The value of the entry is an array of two positive integers,
[ numerator denominator ], denoting a rational magnification factor for the
movie. (See implementation note 153 in Appendix H.) The final window size,
in pixels, is
(numerator ÷ denominator) × Aspect
where the value of Aspect is taken from the movie dictionary (see Table 9.30).
FWPosition
array
(Optional) For floating play windows, the relative position of the window on
the screen. The value is an array of two numbers
[ horiz vert ]
each in the range 0.0 to 1.0, denoting the relative horizontal and vertical posi-
tion of the movie window with respect to the screen. For example, the value
[ 0.5
0.5 ] centers the window on the screen. See implementation note 154 in
Appendix H. Default value: [ 0.5 0.5 ].
9.4
Alternate Presentations
Beginning with PDF 1.4, a PDF document may contain alternate presentations,
which specify alternate ways in which the document may be viewed. The optional
AlternatePresentations entry (PDF 1.4) in a document’s name dictionary (see Ta-
787
SECTION 9.4
Alternate Presentations
ble 3.28) contains a name tree that maps name strings to the alternate presenta-
tions available for the document.
Note: Since PDF viewers are not required to support alternate presentations, au-
thors of documents containing alternate presentations should define the files such
that something useful and meaningful can be displayed and printed. For example, if
the document contains an alternate presentation slideshow of a sequence of photo-
graphs, the photographs should be viewable in a static form by viewers that are not
capable of playing the slideshow.
As of PDF 1.5, the only type of alternate presentation is a slideshow. Slideshows
are typically invoked by means of JavaScript actions (see “JavaScript Actions” on
page 709”) initiated by user action on an interactive form element (see Section
8.6, “Interactive Forms”). Implementation note 155 in Appendix H describes Ac-
robat’s implementation of slideshows.
The following table shows the entries in a slideshow dictionary.
TABLE 9.32 Entries in a slideshow dictionary
KEY
TYPE
VALUE
Type
name
(Required; PDF 1.4) The type of PDF object that this dictionary describes; must be
SlideShow for a slideshow dictionary.
Subtype
name
(Required; PDF 1.4) The subtype of the PDF object that this dictionary describes;
must be Embedded for a slideshow dictionary.
Resources
name tree
(Required; PDF 1.4) A name tree that maps name strings to objects referenced by
the alternate presentation.
Note: Even though PDF treats the strings in the name tree as strings without a speci-
fied encoding, the slideshow interprets them as UTF-8 encoded Unicode.
StartResource byte string
(Required; PDF 1.4) A byte string that must match one of the strings in the Re-
sources entry. It defines the root object for the slideshow presentation.
The Resources name tree represents a virtual file system to the slideshow. It asso-
ciates strings (“file names”) with PDF objects that represent resources used by the
slideshow. For example, a root stream might reference a file name, which would
be looked up in the Resources name tree, and the corresponding object would be
loaded as the file. (This virtual file system is flat; that is, there is no way to refer-
ence subfolders.)
788
CHAPTER 9
Multimedia Features
Typically, images are stored in the document as image XObjects (see Section
4.8.4, “Image Dictionaries”), thereby allowing them to be shared between the
standard PDF representation and the slideshow. Other media objects are stored
or embedded file streams (see Section 3.10.3, “Embedded File Streams”). Also,
see Implementation note 156 in Appendix H.
To allow viewers to verify content against the supported features in a particular
viewer, it is a requirement that all referenced objects include a Type entry in their
dictionary, even when the Type entry is normally optional for a given object.
The following example illustrates the use of alternate presentation slideshows.
Example 9.1
1 0 obj
<</Type /Catalog
/Pages 2 0 R
/Names 3 0 R
% Indirect reference to name dictionary
>>
3 0 obj
% The name dictionary
<</AlternatePresentations 4 0 R >>
endobj
4 0 obj
% The alternate presentations name tree
<</Names [(MySlideShow) 5 0 R]>>
endobj
5 0 obj
% The slideshow definition
<</Type /SlideShow
/Subtype /Embedded
/Resources <</Names [ (mysvg.svg) 31 0R
(abc0001.jpg) 35 0 R (abc0002.jpg) 36 0 R
(mysvg.js) 61 0 R (mymusic.mp3) 65 0 R ]>>
/StartResource (mysvg.svg)
>>
31 0 obj
<</Type /Filespec
% The root object, which
/F (mysvg.svg)
% points to an embedded file stream
/EF <</F 32 0 R>>
>>
endobj
32 0 obj
% The embedded file stream
<</Type /EmbeddedFile
789
SECTION 9.5
3D Artwork
/Subtype /image#2Fsvg+xml
/Length 72
>>
stream
<?xml version="1.0" standalone="no"?>
<svg><!-- Some SVG goes here--></svg>
endstream
endobj
% ... other objects not shown
9.5
3D Artwork
PDF 1.6 introduces the capability for collections of three-dimensional objects,
such as those used by CAD software, to be embedded in PDF files. Such collec-
tions are often called 3D models; in the context of PDF, they are referred to as 3D
artwork. The PDF constructs for 3D artwork support the following features:
• 3D artwork can be rendered within a page; that is, not as a separate window or
user interface element.
• Multiple instances of 3D artwork can appear within a page or document.
• Specific views of 3D artwork can be specified, including a default view that is
displayed initially and other views that can be selected. Views can have names
that can be presented in a user interface.
• (PDF 1.7) Views can specify how 3D artwork should be rendered, colored, lit,
and cross-sectioned, without the use of embedded JavaScript. They can also
specify state information to be applied to individual nodes (3D graphic objects
or collections thereof) in the 3D artwork, such as visibility, opacity, position, or
orientation. (See also implementation note 158 in Appendix H.)
• Pages containing 3D artwork can be printed.
• Users can rotate and move the artwork, enabling them to examine complex ob-
jects from any angle or orientation.
• (PDF 1.7) Keyframe animations contained in 3D artwork can be played in spe-
cific styles and timescales, without programatic intervention. (See also imple-
mentation note 158 in Appendix H.)
790
CHAPTER 9
Multimedia Features
• JavaScripts and other software can programmatically manipulate objects in the
artwork, creating dynamic presentations in which objects move, spin, appear,
and disappear. The JavaScript for Acrobat API Reference (see the Bibliography)
describes the JavaScript interface to 3D annotations.
• (PDF 1.7) The activation of 3D artwork can trigger the display of additional
user interface items in the viewing application. Such items can include model
trees and toolbars. (See also implementation note 158 in Appendix H.)
• Two-dimensional (2D) content such as labels can be overlaid on 3D artwork.
This feature is not the same as the ability to apply 2D markup annotations.
• (PDF 1.7) 2D markup annotations can be applied to specific views of the 3D
artwork, using the ExData entry to identify the 3D annotation and the 3D view
in that annotation. (See also implementation note 158 in Appendix H.)
The following sections describe the major PDF objects that relate to 3D artwork,
as well as providing background information on 3D graphics:
• 3D annotations provide a virtual camera through which the artwork is viewed.
(see Section 9.5.1, “3D Annotations”).
• 3D streams contain the actual specification of a piece of 3D artwork (see Sec-
tion 9.5.2, “3D Streams”). This specification supports the Standard ECMA-363,
Universal 3D file format developed by the 3D Industry Forum (see Bibliogra-
phy). Other formats may be supported in the future.
• 3D views specify information about the relationship between the camera and
the 3D artwork (see Section 9.5.3, “3D Views”). Beginning with PDF 1.7, views
can also describe additional parameters such as render mode, lighting, cross
sections, and nodes. Nodes are 3D graphic objects or collections thereof.
• 3D coordinate systems are described in Section 9.5.4, “Coordinate Systems for
3D.”
• 2D markup annotations applied to 3D artwork views are described in Section
9.5.5, “3D Markup”
Note: Many of the concepts and terminology of 3D rendering are beyond the scope
of this reference. Readers interested in further information are encouraged to con-
sult outside references.
791
SECTION 9.5
3D Artwork
9.5.1
3D Annotations
3D annotations (PDF 1.6) are the means by which 3D artwork is represented in a
PDF document. Table 9.33 shows the entries specific to a 3D annotation dictio-
nary. Table 8.15 on page 606 describes the entries common to all annotation dic-
tionaries.
In addition to these entries, a 3D annotation is required to provide an appearance
stream in its AP entry (see Table 8.15 on page 606) that has a normal appearance
(the N entry in Table 8.19 on page 614). This appearance can be used by applica-
tions that do not support 3D annotations and by all applications for the initial
display of the annotation.
TABLE 9.33 Additional entries specific to a 3D annotation
KEY
TYPE
VALUE
Subtype
name
(Required) The type of annotation that this dictionary describes; must be 3D for
a 3D annotation.
3DD
stream or
(Required) A 3D stream (see Section 9.5.2, “3D Streams”) or 3D reference dictio-
dictionary
nary (see “3D Reference Dictionaries” on page 801) that specifies the 3D art-
work to be shown.
3DV
(various)
(Optional) An object that specifies the default initial view of the 3D artwork that
should be used when the annotation is activated. It can be either a 3D view dic-
tionary (see Section 9.5.3, “3D Views”) or one of the following types specifying
an element in the VA array in the 3D stream (see Table 9.35):
• An integer specifying an index into the VA array.
• A text string matching the IN entry in one of the views in the VA array.
• A name that indicates the first (F), last (L), or default (D) entries in the VA ar-
ray.
Default value: the default view in the 3D stream object specified by 3DD.
3DA
dictionary
(Optional) An activation dictionary (see Table 9.34) that defines the times at
which the annotation should be activated and deactivated and the state of the 3D
artwork instance at those times. Default value: an activation dictionary contain-
ing default values for all its entries.
792
CHAPTER 9
Multimedia Features
KEY
TYPE
VALUE
3DI
boolean
(Optional) A flag indicating the primary use of the 3D annotation. If true, it is
intended to be interactive; if false, it is intended to be manipulated programmat-
ically, as with a JavaScript animation. Viewer applications may present different
user interface controls for interactive 3D annotations (for example, to rotate,
pan, or zoom the artwork) than for those managed by a script or other mecha-
nism.
Default value: true.
3DB
rectangle
(Optional) The 3D view box, which is the rectangular area in which the 3D art-
work is to be drawn. It must be within the rectangle specified by the annotation’s
Rect entry and is expressed in the annotation’s target coordinate system (see be-
low).
Default value: the annotation’s Rect entry, expressed in the target coordinate sys-
tem. This value is [ -w/2 -h/2 w/2 h/2 ], where w and h are the width and height,
respectively, of Rect.
The 3DB entry specifies the 3D view box, a rectangle in which the 3D artwork ap-
pears. The view box must fit within the annotation’s rectangle (specified by its
Rect entry). It may be the same size, or it may be smaller if necessary to provide
extra drawing area for additional 2D graphics within the annotation.
Note: Although 3D artwork can internally specify viewport size, PDF consumer ap-
plications ignore it in favor of information provided by the 3DB entry.
The view box is not specified in the same coordinate system as the annotation’s
rectangle, but rather in the annotation’s target coordinate system, whose origin is
at the center of the annotation’s rectangle. Units in this coordinate system are the
same as default user space units. Therefore, the coordinates of the annotation’s
rectangle in the target coordinate system are
[ -w/2 -h/2 w/2 h/2 ]
given w and h as the rectangle’s width and height.
The 3DD entry specifies a 3D stream that contains the 3D artwork to be shown in
the annotation; 3D streams are described in Section 9.5.2. The 3DD entry can
specify a 3D stream directly; it can also specify a 3D stream indirectly by means
of a 3D reference dictionary (see “3D Reference Dictionaries” on page 801).
793
SECTION 9.5
3D Artwork
These options control whether annotations share the same run-time instance of
the artwork.
The 3DV entry specifies the view of the 3D artwork that is displayed when the an-
notation is activated (as described in the next paragraph). 3D views, which are
described in Section 9.5.3, represent settings for the virtual camera, such as posi-
tion, orientation, and projection style. The view specified by 3DV is one of the 3D
view dictionaries listed in the VA entry in a 3D stream (see Table 9.35).
The 3DA entry is an activation dictionary (see Table 9.34) that determines how
the state of the annotation and its associated artwork can change. These states are
provided to delay the processing or display of 3D artwork until a user chooses to
interact with it. Such delays in activating 3D artwork can be advantageous to per-
formance.
3D annotations can be in one of two states:
• Inactive (the default initial state): the annotation displays the annotation’s nor-
mal appearance.
Note: It is typical, though not required, for the normal appearance to be a pre-
rendered bitmap of the default view of the 3D artwork. Producers should provide
bitmaps of appropriate resolution for all intended uses of the document; for exam-
ple, a high-resolution bitmap for high-quality printing and a screen-resolution
bitmap for on-screen viewing. Optional content (see Section 4.10) can be used to
select the appropriate bitmap for each situation.
• Active: the annotation displays a rendering of the 3D artwork. This rendering is
specified by the annotation’s 3DV entry.
794
CHAPTER 9
Multimedia Features
TABLE 9.34 Entries in a 3D activation dictionary
KEY
TYPE
VALUE
A
name
(Optional) A name specifying the circumstances under which the annotation
should be activated. Valid values are:
PO
The annotation should be activated as soon as the page containing
the annotation is opened.
PV
The annotation should be activated as soon as any part of the page
containing the annotation becomes visible.
XA
The annotation should remain inactive until explicitly activated by
a script or user action.
Note: At any one time, only a single page is considered open in a viewer applica-
tion, even though more than one page may be visible, depending on the page lay-
out.
Default value: XA.
Note: For performance reasons, it is recommended that documents intended for
viewing in a web browser use explicit activation (XA). In non-interactive applica-
tions, such as printing systems or aggregating applications, PO and PV indicate
that the annotation should be activated when the page is printed or placed; XA in-
dicates that the annotation is never activated and the normal appearance should
always be used.
AIS
name
(Optional) A name specifying the state of the artwork instance upon activation
of the annotation. Valid values are:
I
The artwork is instantiated, but real-time script-driven animations
are disabled.
L
Real-time script-driven animations are enabled if present; if not,
the artwork is instantiated.
Default value: L.
Note: In non-interactive applications, the artwork is always instantiated and nev-
er live.
795
SECTION 9.5
3D Artwork
KEY
TYPE
VALUE
D
name
(Optional) A name specifying the circumstances under which the annotation
should be deactivated. Valid values are:
PC
The annotation should be deactivated as soon as the page is closed.
PI
The annotation should be deactivated as soon as the page
containing the annotation becomes invisible.
XD
The annotation should remain active until explicitly deactivated by
a script or user action.
Note: At any one time, only a single page is considered open in the viewer applica-
tion, even though more than one page may be visible, depending on the page lay-
out.
Default value: PI.
DIS
name
(Optional) A name specifying the state of the artwork instance upon deactiva-
tion of the annotation. Valid values are U (uninstantiated), I (instantiated), and
L (live). Default value: U.
Note: If the value of this entry is L, uninstantiation of instantiated artwork is not
required unless it has been modified. Uninstantiation is never required in non-in-
teractive applications.
TB
boolean
(Optional; PDF 1.7) A flag indicating the default behavior of an interactive tool-
bar associated with this annotation. If true, a toolbar should be displayed by de-
fault when the annotation is activated and given focus. If false, a toolbar should
not be displayed by default. Typically, a toolbar is positioned in proximity to the
3D annotation.
Default value: true.
NP
boolean
(Optional; PDF 1.7) A flag indicating the default behavior of the user interface
for viewing or managing information about the 3D artwork. Such user interfac-
es can enable navigation to different views or can depict the hierarchy of the ob-
jects in the artwork (the model tree). If true, the user interface should be made
visible when the annotation is activated. If false, the user interface should not
be made visible by default.
Default value: false
The A and D entries of the activation dictionary determine when a 3D annotation
may become active and inactive. The AIS and DIS entries specify what state the as-
sociated artwork should be in when the annotation is activated or deactivated. 3D
796
CHAPTER 9
Multimedia Features
artwork can be in one of three states:
• Uninstantiated: the initial state of the artwork before it has been used in any
way.
• Instantiated: the state in which the artwork has been read and a run-time in-
stance of the artwork has been created. In this state, it can be rendered but
script-driven real-time modifications (that is, animations) are disabled.
• Live: the artwork is instantiated, and it is being modified in real time to achieve
some animation effect. In the case of keyframe animation, the artwork is live
while it is playing and then reverts to an instantiated state when playing com-
pletes or is stopped.
Note: The live state is valid only for keyframe animations or in interactive viewer
applications that have JavaScript support.
If 3D artwork becomes uninstantiated after having been instantiated, later use of
the artwork requires re-instantiation (animations are lost, and the artwork ap-
pears in its initial form). For this reason, uninstantiation is not actually required
unless the artwork has been modified in some way; consumers may choose to
keep unchanged artwork instantiated for performance reasons.
Note: In non-interactive systems such as printing systems, the artwork cannot be
changed. Therefore, applications can choose to deactivate annotations and unin-
stantiate artwork differently, based on factors such as memory usage and the time
needed to instantiate artwork, and the TB, NP, D and DIS entries may be ignored.
Multiple 3D annotations can share an instance of 3D artwork, as described in “3D
Reference Dictionaries” on page 801. In such a case, the state of the artwork in-
stance is determined in the following way:
• If any annotation dictates (through its activation dictionary) that the artwork
should be live, it is live.
• Otherwise, if any annotation dictates that the artwork should be instantiated, it
is instantiated.
• Otherwise, the artwork is uninstantiated.
Note: Artwork must be either instantiated or live (not be uninstantiated) if any an-
notation referring to it is active. It is, however, possible for artwork to be instantiat-
ed or live if all annotations referring to it are inactive.
797
SECTION 9.5
3D Artwork
9.5.2
3D Streams
Beginning with PDF 1.6, the specification of 3D artwork is contained in a 3D
stream. 3D stream dictionaries, whose entries are shown in Table 9.35, can pro-
vide a set of predefined views of the artwork, as well as a default view. They can
also provide scripts and resources for providing customized behaviors or presen-
tations.
TABLE 9.35 Entries in a 3D stream dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present,
must be 3D for a 3D stream.
Subtype
name
(Required) A name specifying the format of the 3D data contained in the
stream. Currently, the only valid value is U3D.
VA
array
(Optional) An array of 3D view dictionaries, each of which specifies a named
preset view of this 3D artwork (see Section 9.5.3, “3D Views”).
DV
(various)
(Optional) An object that specifies the default (initial) view of the 3D art-
work. It can be a 3D view dictionary (see Section 9.5.3, “3D Views”) or one of
the following types:
• An integer specifying an index into the VA array.
• A text string matching the IN entry in one of the views in the VA array.
• A name that indicates the first (F) or last (L) entries in the VA array.
Default value: 0 (the first entry in the VA array) if VA is present; if VA is not
present, the default view is specified within the 3D stream itself.
Resources
name tree
(Optional) A name tree that maps name strings to objects that can be used by
applications or scripts to modify the default view of the 3D artwork.
The names in this name tree must be text strings so that they can be accessible
from JavaScript.
OnInstantiate
stream
(Optional) A JavaScript script that is executed when the 3D stream is instanti-
ated.
798
CHAPTER 9
Multimedia Features
KEY
TYPE
VALUE
AN
dictionary
(Optional; PDF 1.7) An animation style dictionary indicating the preferred
method that viewer applications should use to drive keyframe animations
present in this artwork (see “3D Animation Style Dictionaries” on page 799).
Default value: an animation style dictionary whose Subtype entry has a value
of None.
The Subtype entry specifies the format of the 3D stream data. The only valid val-
ue is U3D, which indicates that the stream data conforms to the Universal 3D File
Format specification (see Bibliography). PDF consumer applications must be pre-
pared to encounter unknown values for Subtype and recover appropriately,
which usually means leaving the annotation in its inactive state, displaying its
normal appearance.
Note: Applications are encouraged to follow the approach of falling back to the nor-
mal appearance with regard to entries in other dictionaries that may take different
types or values in future PDF versions than the ones specified here.
The VA entry is an array containing a list of named present views of the 3D art-
work. Each entry in the array is a 3D view dictionary (see Section 9.5.3, “3D
Views”) that contains the name of the view and the information needed to display
the view. The order of array elements is the order in which the views are present-
ed in a user interface. The DV entry specifies the view to use as the initial view of
the 3D artwork.
Note: Default views can be specified in the following order of precedence: in the an-
notation dictionary, in the 3D stream dictionary, or in the 3D artwork contained in
the 3D stream.
3D streams contain information that can be used by applications and scripts to
perform animations and other programmatically-defined behaviors, from chang-
ing the viewing orientation to moving individual components of the artwork. The
OnInstantiate entry specifies a JavaScript script that is executed by applications
that support JavaScript whenever a 3D stream is read to create an instance of the
3D artwork. The Resources entry is a name tree that contains objects that can be
used to modify the initial appearance of the 3D artwork. The 3D JavaScript inter-
face for Acrobat is described in JavaScript for Acrobat API Reference (see the Bib-
liography).
799
SECTION 9.5
3D Artwork
3D Animation Style Dictionaries
A 3D animation style dictionary (PDF 1.7) specifies the preferred method that
viewer applications should use to apply timeline scaling to keyframe animations.
It can also specify that keyframe animations be played repeatedly. The AN entry
of the 3D stream can specify a 3D animation style dictionary.
A keyframe animation can be provided as the content of a 3D stream dictionary.
A keyframe animation provides key frames and specifies the mapping for the po-
sition of geometry over a set period of time (animation timeline). Keyframe ani-
mation is an interactive feature that is highly dependent on the behavior and
controls provided by the viewer application.
Table 9.36 shows the entries in an animation style dictionary.
TABLE 9.36 Entries in an 3D animation style dictionary
KEY
TYPE
VALUE
Type
name
(Optional). The type of PDF object that this dictionary describes; if present, must
be 3DAnimationStyle.
Subtype
name
(Optional) The animation style described by this dictionary; see Table 9.37 for
valid values. If an animation style is encountered other than those described in
Table 9.37, an animation style of None is used.
Default value: None
PC
integer
(Optional) An integer specifying the play count for this animation style. A non-
negative integer represents the number of times the animation is played. A nega-
tive integer indicates that the animation is infinitely repeated. This value is ig-
nored for animation styles of type None.
Default value: 0
TM
number
(Optional) A positive number specifying the time multiplier to be used when
running the animation. A value greater than one shortens the time it takes to play
the animation, or effectively speeds up the animation. This allows authors to ad-
just the desired speed of animations, without having to re-author the 3D artwork.
This value is ignored for animation styles of type None.
Default value: 1
800
CHAPTER 9
Multimedia Features
The descriptions of the animation styles (see Table 9.37) use the following vari-
ables to represent application time or keyframe settings specified in the 3D art-
work.
• t is a point on the animation time line. This value is used in conjunction with
the keyframe animation data to determine the state of the 3D artwork.
• [r0, r1] is the keyframe animation time line.
• ta is the current time of the viewer application.
• t0 is the time when the viewer application starts the animation.
• p is the time it takes to play the keyframe animation through one cycle. In the
case of the Linear animation style, one cycle plays the animation through once
from beginning to end. In the case of the Oscillating animation style, one cycle
plays the animation from beginning to end and then from end to beginning.
• m is the positive multiplier specified by the TM entry in the animation style dic-
tionary.
TABLE 9.37 Animation styles
None
Keyframe animations should not be driven directly by the viewer applica-
tion. This value is used by documents that are intended to drive anima-
tions through an alternate means, such as JavaScript.
The remaining entries in the animation style dictionary are ignored.
Linear
Keyframe animations are driven linearly from beginning to end. This ani-
mation style results in a repetitive playthrough of the animation, such as in
a walking motion.
t = (m(ta - t0) + r0) % (r1 - r0)
p = (r1 - r0) / m
The “%” symbol indicates the modulus operator.
Oscillating
Keyframe animations should oscillate along their time range. This anima-
tion style results in a back-and-forth playing of the animation, such as ex-
ploding or collapsing parts.
t = (0.5)(r1 - r0)(1 - cos(m(ta - t0))) + r0
p = 2 * pi / m
801
SECTION 9.5
3D Artwork
3D Reference Dictionaries
It is possible for more than one 3D annotation to be associated with the same 3D
artwork. For example, several annotations might show different views of the same
object. There are two ways in which this association can occur, as determined by
the annotation’s 3DD entry (see Table 9.33):
• If the 3DD entry specifies a 3D stream, the annotation has its own run-time in-
stance of the 3D artwork. Any changes to the artwork are reflected only in this
annotation. Other annotations that refer to the same stream have separate run-
time instances.
• If the 3DD entry specifies a 3D reference dictionary (whose entries are shown
in Table 9.38), the annotation shares a run-time instance of the 3D artwork
with all other annotations that specify the same reference dictionary. Any
changes to the artwork are reflected in all such annotations.
TABLE 9.38 Entries in a 3D reference dictionary
KEY
TYPE
VALUE
Type
name
(Optional) The type of PDF object that this dictionary describes; if present,
must be 3DRef for a 3D reference dictionary.
3DD
stream
(Required) The 3D stream (see Section 9.5.2, “3D Streams”) containing the
specification of the 3D artwork.
Example 9.1 and Figure 9.1 through Figure 9.3 show three annotations that use
the same 3D artwork. Object 100 (Annotation 1) has its own run-time instance of
the 3D stream (object 200); object 101(Annotation 2) and object 102 (Annotation
3) share a run-time instance through the 3D reference dictionary (object 201).
Example 9.2
100 0 obj
% 3D annotation 1
<< /Type /Annot
/Subtype /3D
/3DD 200 0 R
% Reference to the 3D stream containing the 3D artwork
>>
endobj
101 0 obj
% 3D annotation 2
<< /Type /Annot
/Subtype /3D
802
CHAPTER 9
Multimedia Features
/3DD 201 0 R
% Reference to a 3D reference dictionary
>>
endobj
102 0 obj
% 3D annotation 3
<< /Type /Annot
/Subtype /3D
/3DD 201 0 R
% Reference to the same 3D reference dictionary
>>
endobj
200 0 obj
% The 3D stream
<< /Type /3D
/Subtype /U3D
... other keys related to a stream, such as /Length
>>
stream
... U3D data...
endstream
endobj
201 0 obj
% 3D reference dictionary
<< /Type /3DRef
/3DD 200 0 R
% Reference to the actual 3D artwork.
>>
endobj
2
Annotation 1
B
2
Annotation 2
B
2
Annotation 3
B
FIGURE 9.1 Default view of artwork
Большое спасибо!
Ваше мнение очень важно для нас.
Нет комментариевНе стесняйтесь поделиться с нами вашим ценным мнением.
Текст