Repository navigation
PDF Spec 13 Sounds
Part of: PDF-Spec-13-Multimedia-Features
Navigation: PDF-Spec-13-Multimedia | PDF-Spec-Index | PDF-Spec-13-Movies
| T | boolean | (Optional) If true , the floating window shall have a title bar. Default value: true . | | UC | boolean | (Optional; meaningful only if T is true ) If true , the floating window shall 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. |
Table 284 - Entries in a floating window parameters dictionary (continued)
| Key | Type | Value |
|---|---|---|
| TT | array | (Optional; meaningful only if T is true ) An array providing text to display on the floating window's title bar. See 14.9.2.4, 'Multi-language Text Arrays.' If this entry is not present, the conforming reader may provide default text. |
A media offset dictionary (Table 285) shall specify an offset into a media object. The S (subtype) entry indicates how the offset shall be specified: in terms of time, frames or markers. Different media types support different types of offsets.
EXAMPLE Time, '10 seconds'; frames, 'frame 20'; markers, 'Chapter One.'
Table 285 - Entries common to all media offset dictionaries
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be MediaOffset for a media offset dictionary. |
| S | name | (Required) The subtype of media offset dictionary. Valid values shall be: T A media offset time dictionary (see Table 286) F A media offset frame dictionary (see Table 287) M A media offset marker dictionary (see Table 288) The rendition shall be considered non-viable if the conforming reader does not recognize the value of this entry. |
Table 286 - Additional entries in a media offset time dictionary
| Key | Type | Value |
|---|---|---|
| T | dictionary | (Required) A timespan dictionary (see Table 289) that shall specify 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 287 - Additional entries in a media offset frame dictionary
| Key | Type | Value |
|---|---|---|
| F | integer | (Required) Shall specify a frame within a media object. Frame numbers begin at 0; negative frame numbers are not allowed. |
Table 288 - 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. |
A timespan dictionary shall specify a length of time; its entries are shown in Table 289.
Table 289 - Entries in a timespan dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be Timespan for a timespan dictionary. |
| S | name | (Required) The subtype of timespan dictionary. The value shall be S (simple timespan). The rendition shall be considered non-viable if the conforming reader does not recognize the value of this entry. |
| V | number | (Required) The number of seconds in the timespan. Non-integral values shall be allowed. Negative values shall be allowed, but may be disallowed in some contexts. (PDF 1.5) Negative values are not allowed. This entry shall be used only if the value of the S entry is S . Subtypes defined in the future need not use this entry. |
This sub-clause defines several dictionary types that are referenced by the previous sub-clauses.
A media players dictionary may be referenced by media clip data (see 13.2.4.2, 'Media Clip Data') and media play parameters (see 13.2.5, 'Media Play Parameters') dictionaries, and shall allow 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 13.2.7.3, 'Media Player Info Dictionary') that shall provide specific information about each player.
Table 290 - Entries in a media players dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be MediaPlayers for a media players dictionary. |
| MU | array | (Optional) An array of media player info dictionaries (see Table 291) that shall specify a set of players, one of which shall be used in playing the associated media object. Any players specified in NU are effectively removed from MU . 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 dictionaries (see Table 291) that shall 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 shall be ignored. |
| NU | array | (Optional) An array of media player info dictionaries (see Table 291) that shall specify a set of players that shall not be used in playing the associated media object (even if they are also specified in MU ). |
The MU , A , and NU entries each shall specify one or more media player info dictionaries. An empty array shall be treated as if it is not present. The media player info dictionaries shall be allowed to specify overlapping player ranges.
- NOTE 1 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.
If a non-viable media player info dictionary is referenced by MU , NU , or A , it shall be treated as if it were not present in its original array, and a media player info dictionary containing the same software identifier dictionary (see 13.2.7.4, 'Software Identifier Dictionary') shall logically considered present in NU . The same rule shall apply to a media player info dictionary that contains a partially unrecognized software identifier dictionary.
Since both media clip data and media play parameters dictionaries may be employed in a play operation, and each may reference a media players dictionary, there is a potential for conflict between the contents of the two media players dictionaries. At play-time, the viewer shall use the following algorithm to determine whether a player present on the machine may be employed. The player may not be used if any of the following conditions are true:
- a) The content type is known and the player does not support the type.
- b) The player is found in the NU array of either dictionary.
- c) 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.
- d) 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 may be used.
- NOTE 2 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 the Algorithm in 13.2.7.4, 'Software Identifier Dictionary.'
A media player info dictionary shall provide a variety of information regarding a specific media player. Its entries (see Table 291) shall associate information with a particular version or range of versions of a player. As of PDF 1.5, only the PID entry shall provide information about the player, as described in the next sub-clause, 13.2.7.4, 'Software Identifier Dictionary.'
Table 291 - Entries in a media player info dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, |
| PID | dictionary | (Required) A software identifier dictionary (see 13.2.7.4, 'Software Identifier Dictionary') that shall specify the player name, versions, and operating systems to which this media player info dictionary applies. |
| MH | dictionary | (Optional) A dictionary containing entries that shall be honored for this dictionary to be considered viable Currently, there are no defined entries for this dictionary |
| BE | dictionary | (Optional) A dictionary containing entries that need only be honored in a 'best effort' sense. Currently, there are no defined entries for this dictionary |
A software identifier dictionary shall allow software to be identified by name, range of versions, and operating systems; its entries are listed in Table 292. A conforming reader uses this information to determine whether a given media player may be used in a given situation. If the dictionary contains keys that are unrecognized by the conforming reader, it shall be considered to be partially recognized. The conforming reader may or may not decide to treat the software identifier as viable, depending on the context in which it is used.
The following procedure shall be used to determine whether a piece of software is considered to match a software identifier dictionary:
- a) The software name shall match the name specified by the U entry (see 'Software URIs' in 13.2.7.4, 'Software Identifier Dictionary').
- b) The software version shall be within the interval specified by the L , H , LI , and H1 entries (see 'Version arrays' in 13.2.7.4, 'Software Identifier Dictionary').
- c) The machine's operating system name shall be an exact match for one present in the OS array. If the array is not present or empty, a match shall also be considered to exist.
Table 292 - Entries in a software identifier dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be SoftwareIdentifier for a software identifier dictionary. |
| U | ASCII string | (Required) A URI that identifies a piece of software (see 'Software URIs' in 13.2.7.4, 'Software Identifier Dictionary'). |
| L | array | (Optional) The lower bound of the range of software versions that this software identifier dictionary specifies (see 'Version arrays' in 13.2.7.4, 'Software Identifier Dictionary'). 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 shall be greater than or equal to L (see 'Version arrays' in 13.2.7.4, 'Software Identifier Dictionary'). If false , it shall not be inclusive. Default value: true . |
| H | array | (Optional) The upper bound of the range of software versions that this software identifier dictionary specifies (see 'Version arrays' in 13.2.7.4, 'Software Identifier Dictionary'). Default value: an empty array []. |
| HI | boolean | (Optional) If true , the upper bound of the interval defined by L and H is inclusive; that is, the software version shall be less than or equal to H (see 'Version arrays' in 13.2.7.4, 'Software Identifier Dictionary'). If false , it shall not be inclusive. Default value: true . |
| OS | array | (Optional) An array of byte strings representing operating system identifiers that shall indicate to which operating systems this object applies. 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 shall be considered to represent all operating systems. Default value: an empty array. |
The U entry is a URI (universal resource identifier) that identifies a piece of software. It shall be interpreted according to its scheme; the only presently defined scheme is vnd.adobe.swname . The scheme name is caseinsensitive; if shall not be recognized by the conforming reader, the software shall be considered a non-match. The syntax of URIs of this scheme is
'vnd.adobe.swname:' software_name where software_name shall be reg_name as defined in Internet RFC 2396, Uniform Resource Identifiers (URI): Generic Syntax ; see the Bibliography. software_name shall be a sequence of UTF-8-encoded characters that have been escaped with one pass of URL escaping (see 14.10.3.2, 'URL Strings'). That is, to recover the original software name, software_name shall be unescaped and then treated as a sequence of UTF-8 characters. The actual software names shall be compared in a case-sensitive fashion.
Software names shall be second-class names (see Annex E).
EXAMPLE The URI for Adobe Acrobat is vnd.adobe.swname:ADBE_Acrobat
The L , H , LI , and HI entries shall be used to specify a range of software versions. L and H shall be version arrays containing zero or more non-negative integers representing subversion numbers. The first integer shall be the major version numbers, and subsequent integers shall be increasingly minor. H shall be greater than or equal to L , according to the following rules for comparing version arrays:
- a) An empty version array shall be treated as infinity; that is, it shall be considered greater than any other version array except another empty array. Two empty arrays are equal.
- b) When comparing arrays that contain different numbers of elements, the smaller array shall be implicitly padded with zero-valued integers to make the number of elements equal.
EXAMPLE When comparing [5 1 2 3 4] to [5], the latter is treated as [5 0 0 0 0].
- c) The corresponding elements of the arrays shall be compared, starting with the first. When a difference is found, the array containing the larger element shall be considered to have the larger version number. If no differences are found, the versions are equal.
If a version array contains negative numbers, it shall be considered non-viable, as is the enclosing software identifier.
A monitor specifier is an integer that shall identify a physical monitor attached to a system. It may have one of the values in Table 293:
Table 293 - 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, shall treat as case 0 |
| 3 | Monitor with the greatest colour 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 colour depth. Ties may be broken in an implementation-dependent manner.
A sound object (PDF 1.2) shall be a stream containing sample values that define a sound to be played through the computer's speakers. The Sound entry in a sound annotation or sound action dictionary (see Table 185 and Table 208) shall identify a sound object representing the sound to be played when the annotation is activated.
Since a sound object is a stream, it may contain any of the standard entries common to all streams, as described in Table 5. In particular, if it contains an F (file specification) entry, the sound shall be defined in an external file. This sound file shall 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 shall contain the sample data and all other information needed to define the sound. Table 294 shows the additional dictionary entries specific to a sound object.
Table 294 - Additional entries specific to a sound object
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall 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. |
| 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 2 B - 1 Signed Twos-complement values muLaw m-law-encoded samples ALaw A-law-encoded samples Default value: Raw. |
Table 294 - Additional entries specific to a sound object (continued)
| Key | Type | Value |
|---|---|---|
| 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 5 and 7.4, 'Filters.') If this entry is absent, sound compression shall not be used; the data contains sampled waveforms that shall be played at R samples per second per channel. |
| CP | (various) | (Optional) Optional parameters specific to the sound compression format used. No standard values have been defined for the CO and CP entries. |
Sample values shall be stored in the stream with the most significant bits first (big-endian order for samples larger than 8 bits). Samples that are not a multiple of 8 bits shall be packed into consecutive bytes, starting at the most significant end. If a sample extends across a byte boundary, the most significant bits shall be placed in the first byte, followed by less significant bits in subsequent bytes. For dual-channel stereophonic sounds, the samples shall be 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, conforming readers should support at 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 shall be 11,025 or 22,050 samples per channel. If the encoding is muLaw, R shall be 8000 samples per channel, C shall be 1 channel, and B shall be 8 bits per channel. Sound players shall convert between formats, downsample rates, and combine channels as necessary to render sound on the target platform.
The features described in this sub-clause are obsolescent and their use is no longer recommended. They are superseded by the general multimedia framework described in 13.2, 'Multimedia.'
PDF shall embed movies within a document by means of movie annotations (see 12.5.6.17, 'Movie Annotations'). 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 shall refer, respectively, to a movie dictionary (Table 295) that shall describe the static characteristics of the movie and a movie activation dictionary (Table 296) that shall specify how it shall be presented.
Table 295 - 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 shall be left unspecified, and there is no guarantee of portability. |
| Aspect | array | (Optional) The width and height of the movie's bounding box, in pixels, and shall be specified as [width height] . This entry should be omitted for a movie consisting entirely of sound with no visible images. |
| Rotate | integer | (Optional) The number of degrees by which the movie shall be rotated clockwise relative to the page. The value shall be a multiple of 90. Default value: 0. |
| Poster | boolean or stream | (Optional) A flag or stream specifying whether and how a poster image representing the movie shall be displayed. If this value is a stream, it shall contain an image XObject (see 8.9, 'Images') to be displayed as the poster. If it is the boolean value true , the poster image shall be retrieved from the movie file; if it is false , no poster shall be displayed. Default value: false . |
Table 296 - 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 shall be expressed in units of time based on a time scale , which defines the number of units per second. The default time scale shall be defined in the movie data. The starting time shall be 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 Annex C), it shall be specified as such. • If it is not representable as an integer, it shall 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 shall be represented as an array of two values: an integer or byte string denoting the starting time, followed by an integer specifying the time scale in units per second. If this entry is omitted, the movie shall be played from the beginning. |
| Duration | (various) | (Optional) The duration of the movie segment to be played, that shall be specified in the same form as Start . If this entry is omitted, the movie shall be played to the end. |
| Rate | number | (Optional) The initial speed at which to play the movie. If the value of this entry is negative, the movie shall be 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 shall denote greater volume; negative values shall mute the sound. Default value: 1.0. |
| ShowControls | boolean | (Optional) A flag specifying whether to display a movie controller bar while playing the movie. Default value: false . |
Table 296 - Entries in a movie activation dictionary (continued)
| Key | Type | Value |
|---|---|---|
| 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 shall retain control until the movie is completed or dismissed by the user. If the value is false , the player shall return control to the conforming reader immediately after starting the movie. Default value: false . |
| FWScale | array | (Optional) The magnification (zoom) factor at which the movie shall be played. The presence of this entry implies that the movie shall be played in a floating window. If the entry is absent, the movie shall be played in the annotation rectangle. The value of the entry shall be an array of two positive integers, [numerator denominator] , denoting a rational magnification factor for the movie. The final window size, in pixels, shall be ( numerator ÷ denominator ) × Aspect where the value of Aspect shall be taken from the movie dictionary (see Table 295). |
| FWPosition | array | (Optional) For floating play windows, the relative position of the window on the screen. The value shall be an array of two numbers [horiz vert] each in the range 0.0 to 1.0, denoting the relative horizontal and vertical position of the movie window with respect to the screen. EXAMPLE The value [0.5 0.5] centers the window on the screen. Default value: [0.5 0.5]. |
Beginning with PDF 1.4, a PDF document shall 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 Table 31) contains a name tree that maps name strings to the alternate presentations available for the document.
- NOTE 1 Since conforming readers are not required to support alternate presentations, authors 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 photographs, 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 may be invoked by means of JavaScript actions (see 12.6.4.16, 'JavaScript Actions') initiated by user action on an interactive form element (see 12.7, 'Interactive Forms').
The following table shows the entries in a slideshow dictionary.
Table 297 - Entries in a slideshow dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Required; PDF 1.4) The type of PDF object that this dictionary describes; shall be SlideShow for a slideshow dictionary. |
| Subtype | name | (Required; PDF 1.4) The subtype of the PDF object that this dictionary describes; shall 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 specified encoding, the slideshow shall interpret them as UTF-8 encoded Unicode. |
| StartResource | byte string | (Required; PDF 1.4) A byte string that shall match one of the strings in the Resources entry. It shall define the root object for the slideshow presentation. |
- NOTE 2 The Resources name tree represents a virtual file system to the slideshow. It associates strings ('file names') with PDF objects that represent resources used by the slideshow. For example, a root stream may 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 reference subfolders.)
- NOTE 3 Typically, images are stored in the document as image XObjects (see 8.9.5, '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 7.11.4, 'Embedded File Streams').
To allow conforming readers to verify content against their own supported features all referenced objects shall include a Type entry in their dictionary, even when the Type entry is normally optional for a given object.
EXAMPLE The following example illustrates the use of alternate presentation slideshows.
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 /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
Starting with PDF 1.6, collections of three-dimensional objects, such as those used by CAD software, may be embedded in PDF files. Such collections are often called 3D models ; in the context of PDF, they shall be referred to as 3D artwork . The PDF constructs for 3D artwork support the following features:
- 3D artwork may be rendered within a page; that is, not as a separate window or user interface element.
- Multiple instances of 3D artwork may appear within a page or document.
- Specific views of 3D artwork may be specified, including a default view that shall be displayed initially and other views that may be selected. Views may have names that can be presented in a user interface.
- ( PDF 1.7 ) Conforming readers may specify how 3D artwork shall be rendered, coloured, lit, and crosssectioned, without the use of embedded JavaScript. They may also specify state information that shall be applied to individual nodes (3D graphic objects or collections thereof) in the 3D artwork, such as visibility, opacity, position, or orientation.
- Pages containing 3D artwork may be printed.
- Users may rotate and move the artwork, enabling them to examine complex objects from any angle or orientation.
- ( PDF 1.7 ) Keyframe animations contained in 3D artwork may be played in specific styles and timescales, without programatic intervention.
- JavaScripts and other software may programmatically manipulate objects in the artwork, creating dynamic presentations in which objects move, spin, appear, and disappear.
- ( PDF 1.7 ) The activation of 3D artwork can trigger the display of additional user interface items in the conforming reader. Such items may include model trees and toolbars.
- Two-dimensional (2D) content such as labels may 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 may 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.
The following sub-clauses 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 shall be viewed. (see 13.6.2, '3D Annotations').
-
3D streams shall contain the actual specification of a piece of 3D artwork (see 13.6.3, '3D Streams''). This specification supports the Standard ECMA-363, Universal 3D file format developed by the 3D Industry Forum (see Bibliography).
-
3D views shall specify information about the relationship between the camera and the 3D artwork (see 13.6.4, '3D Views'). Beginning with PDF 1.7, views may also describe additional parameters such as render mode, lighting, cross sections, and nodes. Nodes shall be 3D graphic objects or collections thereof.
-
3D coordinate systems are described in 13.6.5, 'Coordinate Systems for 3D.'
-
2D markup annotations applied to 3D artwork views are described in 13.6.6, '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 consult outside references.
3D annotations ( PDF 1.6 ) are the means by which 3D artwork shall be represented in a PDF document. Table 298 shows the entries specific to a 3D annotation dictionary. Table 164 describes the entries common to all annotation dictionaries.
In addition to these entries, a 3D annotation shall provide an appearance stream in its AP entry (see Table 164) that has a normal appearance (the N entry in Table 168). This appearance may be used by applications that do not support 3D annotations and by all applications for the initial display of the annotation.
Table 298 - Additional entries specific to a 3D annotation
| Key | Type | Value |
|---|---|---|
| Subtype | name | (Required) The type of annotation that this dictionary describes; shall be 3D for a 3D annotation. |
| 3DD | stream or dictionary | (Required) A 3D stream (see 13.6.3, '3D Streams') or 3D reference dictionary (see 13.6.3.3, '3D Reference Dictionaries') that specifies the 3D artwork to be shown. |
| 3DV | (various) | (Optional) An object that specifies the default initial view of the 3D artwork that shall be used when the annotation is activated. It may be either a 3D view dictionary (see 13.6.4, '3D Views') or one of the following types specifying an element in the VA array in the 3D stream (see Table 300): • 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 array. Default value: the default view in the 3D stream object specified by 3DD . |
| 3DA | dictionary | (Optional) An activation dictionary (see Table 299) that defines the times at which the annotation shall be activated and deactivated and the state of the 3D artwork instance at those times. Default value: an activation dictionary containing default values for all its entries. |
| 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 programmatically, as with a JavaScript animation. Conforming readers 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 mechanism. Default value: true . |
Table 298 - Additional entries specific to a 3D annotation (continued)
| Key | Type | Value |
|---|---|---|
| 3DB | rectangle | (Optional) The 3D view box, which is the rectangular area in which the 3D artwork shall be drawn. It shall be within the rectangle specified by the annotation's Rect entry and shall be expressed in the annotation's target coordinate system (see discussion following this Table). Default value: the annotation's Rect entry, expressed in the target coordinate system. 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 appears. The view box shall 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 1 Although 3D artwork can internally specify viewport size, conforming readers ignore it in favour of information provided by the 3DB entry.
The view box shall be specified 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 shall specify a 3D stream that contains the 3D artwork to be shown in the annotation; 3D streams are described in Section 13.6.3. The 3DD entry may specify a 3D stream directly; it may also specify a 3D stream indirectly by means of a 3D reference dictionary (see 13.6.3.3, "3D Reference Dictionaries"). These options control whether annotations shall share the same run-time instance of the artwork.
The 3DV entry shall specify the view of the 3D artwork that is displayed when the annotation is activated (as described in the next paragraph). 3D views, which are described in Section 13.6.4, represent settings for the virtual camera, such as position, orientation, and projection style. The view specified by 3DV shall be one of the 3D view dictionaries listed in the VA entry in a 3D stream (see Table 300).
The 3DA entry shall be an activation dictionary (see Table 299) that determines how the state of the annotation and its associated artwork may change.
- NOTE 2 These states serve 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 performance.
At any given moment, a 3D annotation shall be in one of two states:
- Inactive (the default initial state): the annotation displays the annotation's normal appearance.
- NOTE 3 It is typical, though not required, for the normal appearance to be a pre-rendered bitmap of the default view of the 3D artwork. Conforming writers should provide bitmaps of appropriate resolution for all intended uses of the document; for example, a high-resolution bitmap for high-quality printing and a screen-resolution bitmap for on-screen viewing. Optional content (see 8.11, 'Optional Content') may be used to select the appropriate bitmap for each situation.
- Active : the annotation displays a rendering of the 3D artwork. This rendering shall be specified by the annotation's 3DV entry.
Table 299 - Entries in a 3D activation dictionary
| Key | Type | Value |
|---|---|---|
| A | name | (Optional) A name specifying the circumstances under which the annotation shall be activated. Valid values are: PO The annotation shall be activated as soon as the page containing the annotation is opened. PV The annotation shall be activated as soon as any part of the page containing the annotation becomes visible. XA The annotation shall remain inactive until explicitly activated by a script or user action. NOTE 1 At any one time, only a single page shall be considered open in a conforming reader, even though more than one page may be visible, depending on the page layout. Default value: XA . NOTE 2 For performance reasons, documents intended for viewing in a web browser should use explicit activation ( XA ). In non- interactive applications, such as printing systems or aggregating conforming reader, PO and PV indicate that the annotation shall be activated when the page is printed or placed; XA indicates that the annotation shall never be |
| AIS | name | (Optional) A name specifying the state of the artwork instance upon activation of the annotation. Valid values are: I The artwork shall be instantiated, but real-time script-driven animations shall be disabled. L Real-time script-driven animations shall be enabled if present; if not, the artwork shall be instantiated. Default value: L . NOTE 3 In non-interactive conforming readers, the artwork shall be instantiated and scripts shall be disabled. |
| D | name | (Optional) A name specifying the circumstances under which the annotation shall be deactivated. Valid values are: PC The annotation shall be deactivated as soon as the page is closed. PI The annotation shall be deactivated as soon as the page containing the annotation becomes invisible. XD The annotation shall remain active until explicitly deactivated by a script or user action. NOTE 4 At any one time, only a single page shall be considered open in the conforming reader, even though more than one page may be visible, depending on the page layout. |
| DIS | name | (Optional) A name specifying the state of the artwork instance upon deactivation of the annotation. Valid values are U (uninstantiated), I (instantiated), and L (live). Default value: U . NOTE 5 If the value of this entry is L , uninstantiation of instantiated artwork is necessary unless it has been modified. Uninstantiation is never required in non-interactive |
Table 299 - Entries in a 3D activation dictionary (continued)
| Key | Type | Value |
|---|---|---|
| TB | boolean | ( Optional; PDF 1.7 ) A flag indicating the default behavior of an interactive toolbar associated with this annotation. If true , a toolbar shall be displayed by default when the annotation is activated and given focus. If false , a toolbar shall not be displayed by default. NOTE 6 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 interfaces can enable navigation to different views or can depict the hierarchy of the objects 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 determine what state the associated artwork shall be in when the annotation is activated or deactivated. 3D artwork may 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 instance of the artwork has been created. In this state, it may be rendered but script-driven real-time modifications (that is, animations) shall be disabled.
- Live : the artwork has been instantiated, and it is being modified in real time to achieve some animation effect. In the case of keyframe animation, the artwork shall be live while it is playing and then shall revert to an instantiated state when playing completes or is stopped.
- NOTE 4 The live state is valid only for keyframe animations or in interactive conforming readers that have JavaScript support.
If 3D artwork becomes uninstantiated after having been instantiated, later use of the artwork requires reinstantiation (animations are lost, and the artwork appears in its initial form).
- NOTE 5 For this reason, uninstantiation is not necessary unless the artwork has been modified in some way; consumers may choose to keep unchanged artwork instantiated for performance reasons.
- NOTE 6 In non-interactive systems such as printing systems, the artwork cannot be changed. Therefore, applications may choose to deactivate annotations and uninstantiate 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 may share an instance of 3D artwork, as described in 13.6.3.3, "3D Reference Dictionaries". In such a case, the state of the artwork instance shall be determined in the following way:
- If any active annotation dictates (through its activation dictionary) that the artwork shall be live, it shall be live.
- Otherwise, if any active annotation dictates that the artwork shall be instantiated, it shall be instantiated.
- Otherwise (that is, all active annotations dictate that the artwork shall be uninstantiated), the artwork shall be uninstantiated.
The rules described in 13.6.2, '3D Annotations', apply only to active annotations. If all annotations referring to the artwork are inactive, the artwork nevertheless may be uninstantiated, instantiated, or live 3D Streams.
The specification of 3D artwork shall be contained in a 3D stream . 3D stream dictionaries, whose entries (in addition to the regular stream dictionary's entries; see 7.3.7, 'Dictionary Objects') are shown in Table 300, may provide a set of predefined views of the artwork, as well as a default view. They may also provide scripts and resources for providing customized behaviours or presentations.
Table 300 - Entries in a 3D stream dictionary
| Key | Type | Value |
|---|
Navigation: PDF-Spec-13-Multimedia | PDF-Spec-Index | PDF-Spec-13-Movies