Repository navigation
PDF Spec 07 Resources
Part of: PDF-Spec-07-Syntax
Navigation: PDF-Spec-07-Content-Streams | PDF-Spec-Index | Next →
In PDF, all of the operands needed by an operator shall immediately precede that operator. Operators do not return results, and operands shall not be left over when an operator finishes execution.
- NOTE 2 Most operators have to do with painting graphical elements on the page or with specifying parameters that affect subsequent painting operations. The individual operators are described in the clauses devoted to their functions:
Clause 8, "Graphics" describes operators that paint general graphics, such as filled areas, strokes, and sampled images, and that specify device-independent graphical parameters, such as colour.
Clause 9, "Text" describes operators that paint text using character glyphs defined in fonts.
Clause 10, "Rendering" describes operators that specify device-dependent rendering parameters.
Clause 14, "Document Interchange" describes the marked-content operators that associate higher-level logical information with objects in the content stream. These operators do not affect the rendered appearance of the content; they specify information useful to applications that use PDF for document interchange.
Ordinarily, when a conforming reader encounters an operator in a content stream that it does not recognize, an error shall occur. A pair of compatibility operators, BX and EX (PDF 1.1) , shall modify this behaviour (see Table 32). These operators shall occur in pairs and may be nested. They bracket a compatibility section , a portion of a content stream within which unrecognized operators shall be ignored without error. This mechanism enables a conforming writer to use operators defined in later versions of PDF without sacrificing compatibility with older applications. It should be used only in cases where ignoring such newer operators is the appropriate thing to do. The BX and EX operators are not themselves part of any graphics object (see 8.2, "Graphics Objects") or of the graphics state (8.4, "Graphics State").
Table 32 - Compatibility operators
| Operands | Operator | Description |
|---|---|---|
| - | BX | (PDF 1.1) Begin a compatibility section. Unrecognized operators (along with their operands) shall be ignored without error until the balancing EX operator is encountered. |
| - | EX | (PDF 1.1) End a compatibility section begun by a balancing BX operator. Ignore any unrecognized operands and operators from previous matching BX onward. |
As stated above, the operands supplied to operators in a content stream shall only be direct objects; indirect objects and object references shall not be permitted. In some cases, an operator shall refer to a PDF object that is defined outside the content stream, such as a font dictionary or a stream containing image data. This shall be accomplished by defining such objects as named resources and referring to them by name from within the content stream.
Named resources shall be meaningful only in the context of a content stream. The scope of a resource name shall be local to a particular content stream and shall be unrelated to externally known identifiers for objects such as fonts. References from one object outside of content streams to another outside of content streams shall be made by means of indirect object references rather than named resources.
A content stream's named resources shall be defined by a resource dictionary , which shall enumerate the named resources needed by the operators in the content stream and the names by which they can be referred to.
- EXAMPLE 1 If a text operator appearing within the content stream needs a certain font, the content stream's resource dictionary can associate the name F42 with the corresponding font dictionary. The text operator can use this name to refer to the font.
A resource dictionary shall be associated with a content stream in one of the following ways:
- For a content stream that is the value of a page's Contents entry (or is an element of an array that is the value of that entry), the resource dictionary shall be designated by the page dictionary's Resources or is inherited, as described under 7.7.3.4, "Inheritance of Page Attributes," from some ancestor node of the page object.
- For other content streams, a conforming writer shall include a Resources entry in the stream's dictionary specifying the resource dictionary which contains all the resources used by that content stream. This shall apply to content streams that define form XObjects, patterns, Type 3 fonts, and annotation.
- PDF files written obeying earlier versions of PDF may have omitted the Resources entry in all form XObjects and Type 3 fonts used on a page. All resources that are referenced from those forms and fonts shall be inherited from the resource dictionary of the page on which they are used. This construct is obsolete and should not be used by conforming writers.
In the context of a given content stream, the term current resource dictionary refers to the resource dictionary associated with the stream in one of the ways described above.
Each key in a resource dictionary shall be the name of a resource type, as shown in Table 33. The corresponding values shall be as follows:
- For resource type ProcSet , the value shall be an array of procedure set names
- For all other resource types, the value shall be a subdictionary. Each key in the subdictionary shall be the name of a specific resource, and the corresponding value shall be a PDF object associated with the name.
Table 33 - Entries in a resource dictionary
| Key | Type | Value |
|---|---|---|
| ExtGState | dictionary | (Optional) A dictionary that maps resource names to graphics state parameter dictionaries (see 8.4.5, "Graphics State Parameter Dictionaries"). |
| ColorSpace | dictionary | (Optional) A dictionary that maps each resource name to either the name of a device-dependent colour space or an array describing a colour space (see 8.6, "Colour Spaces"). |
| Pattern | dictionary | (Optional) A dictionary that maps resource names to pattern objects (see 8.7, "Patterns"). |
| Shading | dictionary | (Optional; PDF 1.3) A dictionary that maps resource names to shading dictionaries (see 8.7.4.3, "Shading Dictionaries"). |
| XObject | dictionary | (Optional) A dictionary that maps resource names to external objects (see 8.8, "External Objects"). |
| Font | dictionary | (Optional) A dictionary that maps resource names to font dictionaries (see clause 9, "Text"). |
| ProcSet | array | (Optional) An array of predefined procedure set names (see 14.2, "Procedure Sets"). |
Table 33 - Entries in a resource dictionary (continued)
| Key | Type | Value |
|---|---|---|
| Properties | dictionary | (Optional; PDF 1.2) A dictionary that maps resource names to property list dictionaries for marked content (see 14.6.2, "Property Lists"). |
EXAMPLE 2
The following shows a resource dictionary containing procedure sets, fonts, and external objects. The procedure sets are specified by an array, as described in 14.2, "Procedure Sets". The fonts are specified with a subdictionary associating the names F5, F6, F7, and F8 with objects 6, 8, 10, and 12, respectively. Likewise, the XObject subdictionary associates the names Im1 and Im2 with objects 13 and 15, respectively.
<</ProcSet [ /PDF /ImageB ] /Font << /F5 6 0 R /F6 8 0 R /F7 10 0 R /F8 12 0 R >> /XObject << /Im1 13 0 R /Im2 15 0 R >> >>
As mentioned at the beginning of this clause, there are some general-purpose data structures that are built from the basic object types described in 7.3, "Objects," and are used in many places throughout PDF. This subclause describes data structures for text strings, dates, rectangles, name trees, and number trees. More complex data structures are described in 7.10, "Functions," and 7.11, "File Specifications."
All of these data structures are meaningful only as part of the document hierarchy; they may not appear within content streams. In particular, the special conventions for interpreting the values of string objects apply only to strings outside content streams. An entirely different convention is used within content streams for using strings to select sequences of glyphs to be painted on the page (see clause 9, "Text"). Table 34 summarizes the basic and higher-level data types that are used throughout this standard to describe the values of dictionary entries and other PDF data values.
Table 34 - PDF data types
| Type | Description | Sub-Clause |
|---|---|---|
| ASCII string | Bytes containing ASCII characters | 7.9.2 7.9.2.4 |
| array | Array object | 7.3.6 |
| boolean | Boolean value | 7.3.2 |
| byte string | A series of bytes that shall represent characters or other binary data. If such a type represents characters, the encoding shall be determined by the context. | 7.9.2 |
| date | Date (ASCII string) | 7.9.4 |
| dictionary | Dictionary object | 7.3.7 |
| file specification | File specification (string or dictionary) | 7.11 |
Table 34 - PDF data types (continued)
| Type | Description | Sub-Clause |
|---|---|---|
| function | Function (dictionary or stream) | 7.10 |
| integer | Integer number | |
| name | Name object | 7.3.5 |
| name tree | Name tree (dictionary) | 7.9.6 |
| null | Null object | 7.3.9 |
| number | Number (integer or real) | |
| number tree | Number tree (dictionary) | 7.9.7 |
| PDFDocEncoded string | Bytes containing a string that shall be encoded using PDFDocEncoding | 7.9.2 |
| rectangle | Rectangle (array) | 7.9.5 |
| stream | Stream object | 7.3.8 |
| string | Any string that is not a text string. Beginning with PDF 1.7, this type is further qualified as the types: PDFDocEncoded string, ASCII string, and byte string. | 7.9.2 |
| text string | Bytes that represent characters that shall be encoded using either PDFDocEncoding or UTF-16BE with a leading byte-order marker (as defined in 'Text String Type' on page 86.) | 7.9.2.2 7.9.2 |
| text stream | Text stream | 7.9.3 |
PDF supports one fundamental string object (see 7.3.4, "String Objects"). The string object shall be further qualified as a text string, a PDFDocEncoded string, ASCII string, or byte string. The further qualification reflects the encoding used to represent the characters or glyphs described by the string.
Table 35 summarizes the string object types that represent data encoded using specific conventions.
Table 35 - String Object Types
| Type | Description |
|---|---|
| text string | Shall be used for human-readable text, such as text annotations, bookmark names, article names, and document information. These strings shall be encoded using either PDFDocEncoding or UTF-16BE with a leading byte-order marker. This type is described in 7.9.2.2, "Text String Type." |
| PDFDocEncoded string | Shall be used for characters and glyphs that are represented in a single byte, using PDFDocEncoding. This type is described in 7.9.2.3, "PDFDocEncoded String Type." |
Table 35 - String Object Types (continued)
| Type | Description |
|---|---|
| ASCII string | Shall be used for characters that are represented in a single byte using ASCII encoding. |
| byte string | Shall be used for binary data represented as a series of bytes, where each byte can be any value representable in 8 bits. The string may represent characters but the encoding is not known. The bytes of the string need not represent characters. This type shall be used for data such as MD5 hash values, signature certificates, and Web Capture identification values. This type is described in 7.9.2.4, "Byte String Type." |
The string types described in Table 35 specify increasingly specific encoding schemes, as shown in Figure 7.
Figure 7 - Relationship between string types
The text string type shall be used for character strings that contain information intended to be human-readable, such as text annotations, bookmark names, article names, document information, and so forth.
NOTE 1 Text string type is a subtype of string type and represents data encoded using specific conventions.
The text string type shall be used for character strings that shall be encoded in either PDFDocEncoding or the UTF-16BE Unicode character encoding scheme. PDFDocEncoding can encode all of the ISO Latin 1 character set and is documented in Annex D. UTF-16BE can encode all Unicode characters. UTF-16BE and Unicode character encoding are described in the Unicode Standard by the Unicode Consortium (see the Bibliography).
NOTE 2 PDFDocEncoding does not support all Unicode characters whereas UTF-16BE does.
For text strings encoded in Unicode, the first two bytes shall be 254 followed by 255. These two bytes represent the Unicode byte order marker, U+FEFF, indicating that the string is encoded in the UTF-16BE (big-endian) encoding scheme specified in the Unicode standard.
NOTE 3 This mechanism precludes beginning a string using PDFDocEncoding with the two characters thorn ydieresis, which is unlikely to be a meaningful beginning of a word or phrase.
Conforming readers that process PDF files containing Unicode text strings shall be prepared to handle supplementary characters; that is, characters requiring more than two bytes to represent.
An escape sequence may appear anywhere in a Unicode text string to indicate the language in which subsequent text shall be written.
NOTE 4 This is useful when the language cannot be determined from the character codes used in the text.
The escape sequence shall consist of the following elements, in order:
- a) The Unicode value U+001B (that is, the byte sequence 0 followed by 27).
- b) A 2- byte ISO 639 language code.
EXAMPLE en for English or ja for Japanese encoded as ASCII characters.
- c) (Optional) A 2-byte ISO 3166 country code.
EXAMPLE US for the United States or JP for Japan.
- d) The Unicode value U+001B.
- NOTE 5 The complete list of codes defined by ISO 639 and ISO 3166 can be obtained from the International Organization for Standardization (see the Bibliography).
A PDFDocEncoded string is a character string in which the characters shall be represented in a single byte using PDFDocEncoding.
NOTE PDFDocEncoding does not support all Unicode characters whereas UTF-16BE does.
The byte string type shall be used for binary data that shall be represented as a series of bytes, where each byte may be any value representable in 8 bits. Byte string type is a subtype of string type.
- NOTE The string may represent characters but the encoding is not known. The bytes of the string may not represent characters.
A text stream (PDF 1.5) shall be a PDF stream object (7.3.8, "Stream Objects") whose unencoded bytes shall meet the same requirements as a text string (7.9.2.2, "Text String Type") with respect to encoding, byte order, and lead bytes.
Date values used in a PDF shall conform to a standard date format, which closely follows that of the international standard ASN.1 (Abstract Syntax Notation One), defined in ISO/IEC 8824. A date shall be a text string of the form
( D : YYYYMMDDHHmmSSOHH ' mm )
where:
YYYY shall be the year
MM shall be the month (01-12)
DD shall be the day (01-31)
HH shall be the hour (00-23)
mm shall be the minute (00-59)
SS shall be the second (00-59)
O shall be the relationship of local time to Universal Time (UT), and shall be denoted by one of the characters PLUS SIGN (U+002B) (+), HYPHEN-MINUS (U+002D) (-), or LATIN CAPITAL LETTER Z (U+005A) (Z) (see below)
HH followed by APOSTROPHE (U+0027) (') shall be the absolute value of the offset from UT in hours (00-23)
mm shall be the absolute value of the offset from UT in minutes (00-59)
The prefix D: shall be present, the year field (YYYY) shall be present and all other fields may be present but only if all of their preceding fields are also present. The APOSTROPHE following the hour offset field (HH) shall only be present if the HH field is present. The minute offset field (mm) shall only be present if the APOSTROPHE following the hour offset field (HH) is present. The default values for MM and DD shall be both 01; all other numerical fields shall default to zero values. A PLUS SIGN as the value of the O field signifies that local time is later than UT, a HYPHEN-MINUS signifies that local time is earlier than UT, and the LATIN CAPITAL LETTER Z signifies that local time is equal to UT. If no UT information is specified, the relationship of the specified time to UT shall be considered to be GMT. Regardless of whether the time zone is specified, the rest of the date shall be specified in local time.
EXAMPLE For example, December 23, 1998, at 7:52 PM, U.S. Pacific Standard Time, is represented by the string D : 199812231952 - 08 ' 00
Rectangles are used to describe locations on a page and bounding boxes for a variety of objects. A rectangle shall be written as an array of four numbers giving the coordinates of a pair of diagonally opposite corners.
- NOTE Although rectangles are conventionally specified by their lower-left and upper-right corners, it is acceptable to specify any two diagonally opposite corners. Applications that process PDF should be prepared to normalize such rectangles in situations where specific corners are required.
Typically, the array takes the form
[ ll x ll y ur x ur y ]
specifying the lower-left x , lower-left y , upper-right x , and upper-right y coordinates of the rectangle, in that order. The other two corners of the rectangle are then assumed to have coordinates ( ll x , ur y ) and ( ur x , ll y ).
A name tree serves a similar purpose to a dictionary-associating keys and values-but by different means. A name tree differs from a dictionary in the following important ways:
- Unlike the keys in a dictionary, which are name objects, those in a name tree are strings.
- The keys are ordered.
- The values associated with the keys may be objects of any type. Stream objects shall be specified by indirect object references (7.3.8, "Stream Objects"). The dictionary, array, and string objects should be specified by indirect object references, and other PDF objects (nulls, numbers, booleans, and names) should be specified as direct objects.
- The data structure can represent an arbitrarily large collection of key-value pairs, which can be looked up efficiently without requiring the entire data structure to be read from the PDF file. (In contrast, a dictionary can be subject to an implementation limit on the number of entries it can contain.)
A name tree shall be constructed of nodes , each of which shall be a dictionary object. Table 36 shows the entries in a node dictionary. The nodes shall be of three kinds, depending on the specific entries they contain. The tree shall always have exactly one root node , which shall contain a single entry: either Kids or Names but not both. If the root node has a Names entry, it shall be the only node in the tree. If it has a Kids entry, each of the remaining nodes shall be either an intermediate node , that shall contain a Limits entry and a Kids entry, or a leaf node , that shall contain a Limits entry and a Names entry.
Table 36 - Entries in a name tree node dictionary
| Key | Type | Value |
|---|---|---|
| Kids | array | (Root and intermediate nodes only; required in intermediate nodes; present in the root node if and only if Names is not present) Shall be an array of indirect references to the immediate children of this node. The children may be intermediate or leaf nodes. |
| Names | array | (Root and leaf nodes only; required in leaf nodes; present in the root node if and only if Kids is not present) Shall be an array of the form [ key 1 value 1 key 2 value 2 … key n value n ] where each key i shall be a string and the corresponding value i shall be the object associated with that key. The keys shall be sorted in lexical order, as described below. |
| Limits | array | (Intermediate and leaf nodes only; required) Shall be an array of two strings, that shall specify the (lexically) least and greatest keys included in the Names array of a leaf node or in the Names arrays of any leaf nodes that are descendants of an intermediate node. |
The Kids entries in the root and intermediate nodes define the tree's structure by identifying the immediate children of each node. The Names entries in the leaf (or root) nodes shall contain the tree's keys and their associated values, arranged in key-value pairs and shall be sorted lexically in ascending order by key. Shorter keys shall appear before longer ones beginning with the same byte sequence. Any encoding of the keys may be used as long as it is self-consistent; keys shall be compared for equality on a simple byte-by-byte basis.
The keys contained within the various nodes' Names entries shall not overlap; each Names entry shall contain a single contiguous range of all the keys in the tree. In a leaf node, the Limits entry shall specify the least and greatest keys contained within the node's Names entry. In an intermediate node, it shall specify the least and greatest keys contained within the Names entries of any of that node's descendants. The value associated with a given key can thus be found by walking the tree in order, searching for the leaf node whose Names entry contains that key.
EXAMPLE 1 The following is an abbreviated outline, showing object numbers and nodes, of a name tree that maps the names of all the chemical elements, from actinium to zirconium, to their atomic numbers.
1: Root node 2: Intermediate node: Actinium to Gold 5: Leaf node: Actinium = 25, … , Astatine = 31 25: Integer: 89 … 31: Integer: 85 … 11: Leaf node: Gadolinium = 56, … , Gold = 59 56: Integer: 64 … 59: Integer: 79 3: Intermediate node: Hafnium to Protactinium 12: Leaf node: Hafnium = 60, … , Hydrogen = 65 60: Integer: 72 … 65: Integer: 1 …
EXAMPLE 2
19: Leaf node: Palladium = 92, … , Protactinium = 100 92: Integer: 46 … 100:Integer: 91 4: Intermediate node: Radium to Zirconium 20: Leaf node: Radium = 101, … , Ruthenium = 107 101:Integer: 89 … 107:Integer: 85 … 24: Leaf node: Xenon = 129, … , Zirconium = 133 129:Integer: 54 … 133:Integer: 40 The following shows the representation of this tree in a PDF file 1 0 obj << /Kids [ 2 0 R % Root node 3 0 R 4 0 R ] >> endobj 2 0 obj << /Limits [ ( Actinium ) ( Gold ) ] % Intermediate node /Kids [ 5 0 R 6 0 R 7 0 R 8 0 R 9 0 R 10 0 R 11 0 R ] >> endobj 3 0 obj << /Limits [ ( Hafnium ) ( Protactinium ) ] % Intermediate node /Kids [ 12 0 R 13 0 R 14 0 R 15 0 R 16 0 R 17 0 R 18 0 R 19 0 R ] >> endobj 4 0 obj << /Limits [ ( Radium ) ( Zirconium ) ] % Intermediate node /Kids [ 20 0 R 21 0 R 22 0 R 23 0 R 24 0 R ] >> endobj 5 0 obj << /Limits [ ( Actinium ) ( Astatine ) ] % Leaf node /Names [ ( Actinium ) 25 0 R
( Aluminum ) 26 0 R ( Americium ) 27 0 R ( Antimony ) 28 0 R ( Argon ) 29 0 R ( Arsenic ) 30 0 R ( Astatine ) 31 0 R ] >> endobj … 24 0 obj << /Limits [ ( Xenon ) ( Zirconium ) ] % Leaf node /Names [ ( Xenon ) 129 0 R ( Ytterbium ) 130 0 R ( Yttrium ) 131 0 R ( Zinc ) 132 0 R ( Zirconium ) 133 0 R ] >> endobj 25 0 obj 89 % Atomic number (Actinium) endobj … 133 0 obj 40 % Atomic number (Zirconium) endobj
A number tree is similar to a name tree (see 7.9.6, "Name Trees"), except that its keys shall be integers instead of strings and shall be sorted in ascending numerical order. The entries in the leaf (or root) nodes containing the key-value pairs shall be named Nums instead of Names as in a name tree. Table 37 shows the entries in a number tree's node dictionaries.
Table 37 - Entries in a number tree node dictionary
| Key | Type | Value |
|---|---|---|
| Kids | array | (Root and intermediate nodes only; required in intermediate nodes; present in the root node if and only if Nums is not present) Shall be an array of indirect references to the immediate children of this node. The children may be intermediate or leaf nodes. |
| Nums | array | (Root and leaf nodes only; shall be required in leaf nodes; present in the root node if and only if Kids is not present) Shall be an array of the form [ key 1 value 1 key 2 value 2 … key n value n ] where each key i is an integer and the corresponding value i shall be the object associated with that key. The keys shall be sorted in numerical order, analogously to the arrangement of keys in a name tree as described in 7.9.6, "Name Trees." |
| Limits | array | (Shall be present in Intermediate and leaf nodes only) Shall be an array of two integers, that shall specify the (numerically) least and greatest keys included in the Nums array of a leaf node or in the Nums arrays of any leaf nodes that are descendants of an intermediate node. |
PDF is not a programming language, and a PDF file is not a program. However, PDF provides several types of function objects (PDF 1.2) that represent parameterized classes of functions, including mathematical formulas and sampled representations with arbitrary resolution.
NOTE 1 Functions may be used in various ways in PDF, including device-dependent rasterization information for highquality printing (halftone spot functions and transfer functions), colour transform functions for certain colour spaces, and specification of colours as a function of position for smooth shadings.
Functions in PDF represent static, self-contained numerical transformations.
NOTE 2 A function to add two numbers has two input values and one output value:
Similarly, a function that computes the arithmetic and geometric mean of two numbers can be viewed as a function of two input values and two output values:
In general, a function can take any number (m) of input values and produce any number (n) of output values:
In PDF functions, all the input values and all the output values shall be numbers, and functions shall have no side effects.
Each function definition includes a domain , the set of legal values for the input. Some types of functions also define a range , the set of legal values for the output. Input values passed to the function shall be clipped to the domain, and output values produced by the function shall be clipped to the range.
Suppose the following function is defined with a domain of [-1 1 ]. If the function is called with the input value 6, that value is replaced with the nearest value in the defined domain, 1, before the function is
EXAMPLE evaluated; the resulting output value is therefore 3.
Similarly, if the following function is defined with a range of [ 0 100 ], and if the input values -6 and 4 are passed to the function (and are within its domain), then the output value produced by the function, -14, is replaced with 0, the nearest value in the defined range.
A function object may be a dictionary or a stream, depending on the type of function. The term function dictionary is used generically in this sub-clause to refer to either a dictionary object or the dictionary portion of a stream object. A function dictionary specifies the function's representation, the set of attributes that parameterize that representation, and the additional data needed by that representation. Four types of functions are available, as indicated by the dictionary's FunctionType entry:
-
(PDF 1.2) A sampled function (type 0) uses a table of sample values to define the function. Various techniques are used to interpolate values between the sample values; see 7.10.2, "Type 0 (Sampled) Functions."
-
(PDF 1.3) An exponential interpolation function (type 2) defines a set of coefficients for an exponential function; see 7.10.3, "Type 2 (Exponential Interpolation) Functions."
-
(PDF 1.3) A stitching function (type 3) is a combination of other functions, partitioned across a domain; see 7.10.4, "Type 3 (Stitching) Functions."
-
(PDF 1.3) A PostScript calculator function (type 4) uses operators from the PostScript language to describe an arithmetic expression; see 7.10.5, "Type 4 (PostScript Calculator) Functions."
All function dictionaries shall share the entries listed in Table 38.
Table 38 - Entries common to all function dictionaries
| Key | Type | Value |
|---|---|---|
| FunctionType | integer | (Required) The function type: 0 Sampled function 2 Exponential interpolation function 3 Stitching function 4 PostScript calculator function |
| Domain | array | (Required) An array of 2 × m numbers, where m shall be the number of input values. For each i from 0 to m - 1, Domain 2 i shall be less than or equal to Domain 2 i + 1 , and the i th input value, x i , shall lie in the interval Domain 2 i ≤ x i ≤ Domain 2 i + 1 . Input values outside the declared domain shall be clipped to the nearest boundary value. |
| Range | array | (Required for type 0 and type 4 functions, optional otherwise; see below) An array of 2 × n numbers, where n shall be the number of output values. For each j from 0 to n - 1, Range 2 j shall be less than or equal to Range 2 j +1 , and the j th output value, y j , shall lie in the interval Range 2 j ≤ y j ≤ Range 2 j +1 . Output values outside the declared range shall be clipped to the nearest boundary value. If this entry is absent, no clipping shall be done. |
In addition, each type of function dictionary shall include entries appropriate to the particular function type. The number of output values can usually be inferred from other attributes of the function; if not (as is always the case for type 0 and type 4 functions), the Range entry is required. The dimensionality of the function implied by the Domain and Range entries shall be consistent with that implied by other attributes of the function.
Type 0 functions use a sequence of sample values (contained in a stream) to provide an approximation for functions whose domains and ranges are bounded. The samples are organized as an m -dimensional table in which each entry has n components.
- NOTE 1 Sampled functions are highly general and offer reasonably accurate representations of arbitrary analytic functions at low expense. For example, a 1-input sinusoidal function can be represented over the range [ 0 180 ] with an average error of only 1 percent, using just ten samples and linear interpolation. Two-input functions require significantly more samples but usually not a prohibitive number if the function does not have high frequency variations.
There shall be no dimensionality limit of a sampled function except for possible implementation limits.
- NOTE 2 The number of samples required to represent functions with high dimensionality multiplies rapidly unless the sampling resolution is very low. Also, the process of multilinear interpolation becomes computationally intensive if the number of inputs m is greater than 2. The multidimensional spline interpolation is even more computationally intensive.
In addition to the entries in Table 38, a type 0 function dictionary includes those shown in Table 39.
The Domain , Encode , and Size entries determine how the function's input variable values are mapped into the sample table. For example, if Size is [ 21 31 ], the default Encode array shall be [ 0 20 0 30 ], which maps the entire domain into the full set of sample table entries. Other values of Encode may be used.
To explain the relationship between Domain , Encode , Size , Decode , and Range , we use the following notation:
For a given value of x , Interpolate calculates the y value on the line defined by the two points ( x min , y min ) and ( x max , y max ).
Table 39 - Additional entries specific to a type 0 function dictionary
| Key | Type | Value |
|---|---|---|
| Size | array | (Required) An array of m positive integers that shall specify the number of samples in each input dimension of the sample table. |
| BitsPerSample | integer | (Required) The number of bits that shall represent each sample. (If the function has multiple output values, each one shall occupy BitsPerSample bits.) Valid values shall be 1, 2, 4, 8, 12, 16, 24, and 32. |
| Order | integer | (Optional) The order of interpolation between samples. Valid values shall be 1 and 3, specifying linear and cubic spline interpolation, respectively. Default value: 1. |
| Encode | array | (Optional) An array of 2 × m numbers specifying the linear mapping of input values into the domain of the function's sample table. Default value: [0 ( Size 0 - 1) 0 ( Size 1 - 1) …]. |
| Decode | array | (Optional) An array of 2 × n numbers specifying the linear mapping of sample values into the range appropriate for the function's output values. Default value: same as the value of Range . |
| other stream attributes | (various) | (Optional) Other attributes of the stream that shall provide the sample values, as appropriate (see Table 5). |
When a sampled function is called, each input value x i , for 0 £ i < m , shall be clipped to the domain:
That value shall be encoded:
That value shall be clipped to the size of the sample table in that dimension:
The encoded input values shall be real numbers, not restricted to integers. Interpolation shall be used to determine output values from the nearest surrounding values in the sample table. Each output value r j , for 0 £ j < n , shall then be decoded:
r j ′ Interpolate r j 0 2 BitsPerSample 1 -Decode 2 j Decode 2 j 1 + , , , , ) ( =
Finally, each decoded value shall be clipped to the range:
Sample data shall be represented as a stream of bytes. The bytes shall constitute a continuous bit stream, with the high-order bit of each byte first. Each sample value shall be represented as a sequence of BitsPerSample bits. Successive values shall be adjacent in the bit stream; there shall be no padding at byte boundaries.
For a function with multidimensional input (more than one input variable), the sample values in the first dimension vary fastest, and the values in the last dimension vary slowest.
EXAMPLE 1 For a function f ( a , b , c ), where a , b , and c vary from 0 to 9 in steps of 1, the sample values would appear in this order: f (0, 0, 0), f (1, 0, 0), … , f (9, 0, 0), f (0, 1, 0), f (1, 1, 0), … , f (9, 1, 0), f (0, 2, 0), f (1, 2, 0), … , f (9, 9, 0), f (0, 0, 1), f (1, 0, 1), and so on.
For a function with multidimensional output (more than one output value), the values shall be stored in the same order as Range .
The stream data shall be long enough to contain the entire sample array, as indicated by Size , Range , and BitsPerSample ; see 7.3.8.2, "Stream Extent."
Example 2 illustrates a sampled function with 4-bit samples in an array containing 21 columns and 31 rows (651 values). The function takes two arguments, x and y , in the domain [-1.0 1.0 ], and returns one value, z , in that same range. The x argument shall be linearly transformed by the encoding to the domain [ 0 20 ] and the y argument to the domain [ 0 30 ]. Using bilinear interpolation between sample points, the function computes a value for z , which (because BitsPerSample is 4) will be in the range [ 0 15 ], and the decoding transforms z to a number in the range [ -1.0 1.0 ] for the result. The sample array shall be stored in a string of 326 bytes, calculated as follows (rounded up):
326 bytes = 31 rows ¥ 21 samples / row ¥ 4 bits / sample ³ 8 bits / byte
The first byte contains the sample for the point (-1.0, -1.0) in the high-order 4 bits and the sample for the point (-0.9, -1.0) in the low-order 4 bits.
EXAMPLE 2 14 0 obj << /FunctionType 0 /Domain [-1.0 1.0 -1.0 1.0 ] /Size [ 21 31 ] /Encode [ 0 20 0 30 ] /BitsPerSample 4 /Range [ -1.0 1.0 ] /Decode [ -1.0 1.0 ] /Length … /Filter … >> stream … 651 sample values … endstream endobj
- NOTE 3 The Decode entry can be used creatively to increase the accuracy of encoded samples corresponding to certain values in the range.
- EXAMPLE 3 If the range of the function is [ -1.0 1.0 ] and BitsPerSample is 4, the usual value of Decode would be [ -1.0 1.0 ] and the sample values would be integers in the interval [ 0 15 ] (as shown in Figure 8). But if these values are used, the midpoint of the range, 0.0, is not represented exactly by any sample value, since it falls halfway between 7 and 8. However, if the Decode array is [ -1.0 +1.1429 ] (1.1429 being
approximately equal to 16 ³ 14) and the sample values supplied are in the interval [ 0 14 ], the effective range of [ -1.0 1.0 ] is achieved, and the range value 0.0 is represented by the sample value 7.
The Size value for an input dimension can be 1, in which case all input values in that dimension shall be mapped to the single allowed value. If Size is less than 4, cubic spline interpolation is not possible and Order 3 shall be ignored if specified.
Figure 8 - Mapping with the Decode array
Type 2 functions (PDF 1.3) include a set of parameters that define an exponential interpolation of one input value and n output values:
In addition to the entries in Table 38, a type 2 function dictionary shall include those listed in Table 40.
Table 40 - Additional entries specific to a type 2 function dictionary
| Key | Type | Value |
|---|---|---|
| C0 | array | (Optional) An array of n numbers that shall define the function result when x = 0.0. Default value: [0.0]. |
| C1 | array | (Optional) An array of n numbers that shall define the function result when x = 1.0. Default value: [1.0]. |
| N | number | (Required) The interpolation exponent. Each input value x shall return n values, given by y j = C0 j + x N × ( C1 j - C0 j ), for 0 ≤ j < n . |
Values of Domain shall constrain x in such a way that if N is not an integer, all values of x shall be nonnegative, and if N is negative, no value of x shall be zero. Typically, Domain is declared as [ 0.0 1.0 ], and N is a positive number. To clip the output to a specified range The Range attribute shall be used.
NOTE When N is 1, the function performs a linear interpolation between C0 and C1 ; therefore, the function can also be expressed as a sampled function (type 0).
Type 3 functions (PDF 1.3) define a stitching of the subdomains of several 1-input functions to produce a single new 1-input function. Since the resulting stitching function is a 1-input function, the domain is given by a twoelement array, [ Domain 0 Domain 1 ].
In addition to the entries in Table 38, a type 3 function dictionary shall include those listed in Table 41.
Table 41 - Additional entries specific to a type 3 function dictionary
| Key | Type | Value |
|---|---|---|
| Functions | array | (Required) An array of k 1-input functions that shall make up the stitching function. The output dimensionality of all functions shall be the same, and compatible with the value of Range if Range is present. |
| Bounds | array | (Required) An array of k - 1 numbers that, in combination with Domain , shall define the intervals to which each function from the Functions array shall apply. Bounds elements shall be in order of increasing value, and each value shall be within the domain defined by Domain . |
| Encode | array | (Required) An array of 2 × k numbers that, taken in pairs, shall map each subset of the domain defined by Domain and the Bounds array to the domain of the corresponding function. |
Domain shall be of size 2 (that is, m = 1), and Domain 0 shall be strictly less than Domain 1 unless k = 1. The domain shall be partitioned into k subdomains, as indicated by the dictionary's Bounds entry, which shall be an array of k - 1 numbers that obey the following relationships (with exceptions as noted below):
The Bounds array shall describe a series of half-open intervals, closed on the left and open on the right (except the last, which is closed on the right as well). The value of the Functions entry shall be an array of k functions. The first function shall apply to x values in the first subdomain, Domain 0 £ x < Bounds 0 ; the second function shall apply to x values in the second subdomain, Bounds 0 £ x < Bounds 1 ; and so on. The last function shall apply to x values in the last subdomain, which includes the upper bound:
Bounds k -2 £ x £ Domain 1 . The value of k may be 1, in which case the Bounds array shall be empty and the single item in the Functions array shall apply to all x values, Domain 0 £ x £ Domain 1 .
The Encode array contains 2 ¥ k numbers. A value x from the i th subdomain shall be encoded as follows:
x ′ Interpolate x Bounds i 1 -Bounds i · Encode 2 i Encode 2 i 1 + , , , , ) ( =
for 0 £ i < k . In this equation, Bounds -1 means Domain 0 , and Bounds k -1 means Domain 1 . If the last bound, Bounds k -2 , is equal to Domain 1 , then x ¢ shall be defined to be Encode 2 i .
NOTE The stitching function is designed to make it easy to combine several functions to be used within one shading pattern over different parts of the shading's domain. Shading patterns are discussed in 8.7.4, "Shading Patterns". The same effect could be achieved by creating a separate shading dictionary for each of the functions, with adjacent domains. However, since each shading would have similar parameters, and because the overall effect is one shading, it is more convenient to have a single shading with multiple function definitions. Also, type 3 functions provide a general mechanism for inverting the domains of 1-input functions.
EXAMPLE Consider a function f with a Domain of [ 0.0 1.0 ] and a stitching function g with a Domain of [ 0.0 1.0 ], a Functions array containing f , and an Encode array of [ 1.0 0.0 ]. In effect, g ( x ) = f (1 x ).
A type 4 function (PDF 1.3) , also called a PostScript calculator function, shall be represented as a stream containing code written in a small subset of the PostScript language.
- NOTE Although any function can be sampled (in a type 0 PDF function) and others can be described with exponential functions (type 2 in PDF), type 4 functions offer greater flexibility and potentially greater accuracy. For example, a tint transformation function for a hexachrome (six-component) DeviceN colour space with an alternate colour space of DeviceCMYK (see 8.6.6.5, "DeviceN Colour Spaces") requires a 6-in, 4-out function. If such a function were sampled with m values for each input variable, the number of samples, 4 ¥ m 6 , could be prohibitively large. In practice, such functions can often be written as short, simple PostScript functions.
Type 4 functions also make it possible to include a wide variety of halftone spot functions without the loss of accuracy that comes from sampling, and without adding to the list of predefined spot functions (see 10.5.3, "Spot Functions"). All of the predefined spot functions can be written as type 4 functions.
The language that shall be used in a type 4 function contains expressions involving integers, real numbers, and boolean values only. There shall be no composite data structures such as strings or arrays, no procedures, and no variables or names. Table 42 lists the operators that can be used in this type of function. (For more information on these operators, see Appendix B of the PostScript Language Reference , Third Edition.) Although the semantics are those of the corresponding PostScript operators, a full PostScript interpreter is not required.
Table 42 - Operators in type 4 functions
| Operator Type | Operators | Operators | Operators | Operators | Operators |
|---|---|---|---|---|---|
| Arithmetic operators | abs add atan ceiling cos | cvi cvr div exp | floor idiv ln log | mod mul neg round | sin sqrt sub truncate |
| Relational, boolean, and bitwise operators | and bitshift eq | false ge gt | le lt ne | not or | true xor |
| Conditional operators | if | ifelse | |||
| Stack operators | copy dup | exch index | pop roll |
The operand syntax for type 4 functions shall follow PDF conventions rather than PostScript conventions. The entire code stream defining the function shall be enclosed in braces { } (using LEFT CURLY BRACE (7Bh) and RIGHT CURLY BRACE (07hD)). Braces also shall delimit expressions that are executed conditionally by the if and ifelse operators:
- boolean { expression } if
- boolean { expression 1 } { expression 2 } ifelse
This construct is purely syntactic; unlike in PostScript, no 'procedure objects' shall be involved.
A type 4 function dictionary shall include the entries in Table 38, as well as other appropriate stream attributes (see Table 5). The following example shows a type 4 function equivalent to the predefined spot function DoubleDot (see 10.5.3, "Spot Functions").
EXAMPLE 10 0 obj << /FunctionType 4 /Domain [ -1.0 1.0 -1.0 1.0 ] /Range [ -1.0 1.0 ] /Length 71 >> stream
{ 360 mul sin 2 div exch 360 mul sin 2 div add } endstream endobj
The Domain and Range entries shall both be required. The input variables shall constitute the initial operand stack; the items remaining on the operand stack after execution of the function shall be the output variables. It shall be an error for the number of remaining operands to differ from the number of output variables specified by Range or for any of them to be objects other than numbers.
Implementations of type 4 functions shall provide a stack with room for at least 100 entries. No implementation shall be required to provide a larger stack, and it shall be an error to overflow the stack.
Although any integers or real numbers that may appear in the stream fall under the same implementation limits (defined in Annex C) as in other contexts, the intermediate results in type 4 function computations shall not. An implementation may use a representation that exceeds those limits. Operations on real numbers, for example, might use single-precision or double-precision floating-point numbers.
The part of a conforming reader that reads a type 4 function (analogous to the PostScript scanner ) shall detect and report syntax errors. Any errors detected by the conforming reader shall be errors in the PDF file and shall be handled like other errors in the file.
The part of a conforming reader that executes a type 4 function (analogous to the PostScript interpreter ) shall detect and report errors. This specification does not define a representation for the errors; those details shall be provided by the conforming reader that processes the PDF file. The following types of errors can occur (among others):
- Stack overflow
- Stack underflow
- A type error (for example, applying not to a real number)
- A range error (for example, applying sqrt to a negative number)
- An undefined result (for example, dividing by 0)
A PDF file can refer to the contents of another file by using a file specification (PDF 1.1) , which shall take either of two forms:
- A simple file specification shall give just the name of the target file in a standard format, independent of the naming conventions of any particular file system. It shall take the form of either a string or a dictionary
- A full file specification shall include information related to one or more specific file systems. It shall only be represented as a dictionary.
A file specification shall refer to a file external to the PDF file or to a file embedded within the referring PDF file, allowing its contents to be stored or transmitted along with the PDF file. The file shall be considered to be external to the PDF file in either case.
The standard format for representing a simple file specification in string form divides the string into component substrings separated by the SOLIDUS character (2Fh) (/). The SOLIDUS is a generic component separator that shall be mapped to the appropriate platform-specific separator when generating a platform-dependent file name. Any of the components may be empty. If a component contains one or more literal SOLIDI, each shall be preceded by a REVERSE SOLIDUS (5Ch) (), which in turn shall be preceded by another REVERSE SOLIDUS to indicate that it is part of the string and not an escape character.
EXAMPLE
( in \ \ /out ) represents the file name in / out
The REVERSE SOLIDI shall be removed in processing the string; they are needed only to distinguish the component values from the component separators. The component substrings shall be stored as bytes and shall be passed to the operating system without interpretation or conversion of any sort.
A simple file specification that begins with a SOLIDUS shall be an absolute file specification. The last component shall be the file name; the preceding components shall specify its context. In some file specifications, the file name may be empty; for example, URL (uniform resource locator) specifications can specify directories instead of files. A file specification that does not begin with a SOLIDUS shall be a relative file specification giving the location of the file relative to that of the PDF file containing it.
In the case of a URL-based file system, the rules of Internet RFC 1808, Relative Uniform Resource Locators (see the Bibliography), shall be used to compute an absolute URL from a relative file specification and the specification of the PDF file. Prior to this process, the relative file specification shall be converted to a relative URL by using the escape mechanism of RFC 1738, Uniform Resource Locators , to represent any bytes that would be either unsafe according to RFC 1738 or not representable in 7-bit U.S. ASCII. In addition, such URLbased relative file specifications shall be limited to paths as defined in RFC 1808. The scheme, network location/login, fragment identifier, query information, and parameter sections shall not be allowed.
In the case of other file systems, a relative file specification shall be converted to an absolute file specification by removing the file name component from the specification of the containing PDF file and appending the relative file specification in its place.
EXAMPLE 1 The relative file specification
ArtFiles / Figure1 . pdf appearing in a PDF file whose specification is
/ HardDisk / PDFDocuments / AnnualReport / Summary . pdf yields the absolute specification
/ HardDisk / PDFDocuments / AnnualReport / ArtFiles / Figure1 . pdf
The special component . . (two PERIODs) (2Eh) can be used in a relative file specification to move up a level in the file system hierarchy. After an absolute specification has been derived, when the component immediately preceding . . is not another . . , the two cancel each other; both are eliminated from the file specification and the process is repeated.
- EXAMPLE 2 The relative file specification from EXAMPLE 1 in this sub-clause using the .. (two PERIODs) special component
. . /. . / ArtFiles / Figure1 . pdf would yield the absolute specification
/ HardDisk / ArtFiles / Figure1 . pdf
The conversion of a file specification to a platform-dependent file name depends on the specific file naming conventions of each platform:
- For DOS, the initial component shall be either a physical or logical drive identifier or a network resource name as returned by the Microsoft Windows function WNetGetConnection, and shall be followed by a COLON (3Ah) ( : ). A network resource name shall be constructed from the first two components; the first component shall be the server name and the second shall be the share name (volume name). All components shall be separated by REVERSE SOLIDI (backslashes) (5Ch). It shall be possible to specify an absolute DOS path without a drive by making the first component empty. (Empty components are ignored by other platforms.)
- For Mac OS, all components shall be separated by COLONs.
- For UNIX, all components shall be separated by SOLIDI (2Fh) (slashes). An initial SOLIDUS, if present, shall be preserved.
Strings used to specify a file name shall be interpreted in the standard encoding for the platform on which the document is being viewed. Table 43 shows examples of file specifications on the most common platforms.
Table 43 - Examples of file specifications
| System | System-dependent paths | Written form |
|---|---|---|
| DOS | \pdfdocs\spec.pdf (no drive) r:\pdfdocs\spec.pdf pclib/eng:\pdfdocs\spec.pdf | (//pdfdocs/spec.pdf) (/r/pdfdocs/spec.pdf) (/pclib/eng/pdfdocs/ spec.pdf) |
| Mac OS | Mac HD:PDFDocs:spec.pdf | (/Mac HD/PDFDocs/ spec.pdf) |
| UNIX | /user/fred/pdfdocs/spec.pdf pdfdocs/spec.pdf (relative) | (/user/fred/pdfdocs/ spec.pdf) (pdfdocs/spec.pdf) |
- NOTE 1 When creating documents that are to be viewed on multiple platforms, care should be taken to ensure file name compatibility. Only a subset of the U.S. ASCII character set should be used in file specifications: the uppercase alphabetic characters (A-Z), the numeric characters (0-9), the PERIOD (2Eh) and the LOW LINE (underscore) (5Fh). The PERIOD has special meaning in DOS and Windows file names, and as the first character in a Mac OS pathname. In file specifications, the PERIOD should be used only to separate a base file name from a file extension.
- NOTE 2 Some file systems are case-insensitive, and names within a directory are unique so names should remain distinguishable if lowercase letters are changed to uppercase or vice versa. On DOS and Windows 3.1 systems and on some CD-ROM file systems, file names are limited to 8 characters plus a 3-character extension. File system software typically converts long names to short names by retaining the first 6 or 7 characters of the file name and the first 3 characters after the last PERIOD, if any. Since characters beyond the sixth or seventh are often converted to other values unrelated to the original value, file names should be distinguishable from the first 6 characters.
In PDF 1.2 or higher, a file specification may contain multiple-byte character codes, represented in hexadecimal form between angle brackets (< and >) (using LESS-THAN SIGN (3Ch) and GREATER-THAN SIGN (3Eh)). Since the SOLIDUS (2Fh) (slash character), denoted as < 2F >, is used as a component delimiter and the REVERSE SOLIDUS (5Ch) (backslash character), denoted as < 5C >, is used as an escape character, any occurrence of either of these bytes in a multiple-byte character shall be preceded by the ASCII code for the SOLIDUS (2Fh).
A file name containing the 2-byte character code < 89 5C > is written as < 89 5C 5C >. When the application encounters this sequence of bytes in a file name, it replaces the sequence with the original
EXAMPLE 2-byte code.
The dictionary form of file specification provides more flexibility than the string form, allowing different files to be specified for different file systems or platforms, or for file systems other than the standard ones (DOS/Windows, Mac OS, and UNIX). Table 44 shows the entries in a file specification dictionary. Regardless of the platform, conforming readers should use the F and UF (beginning with PDF 1.7) entries to specify files. The UF entry is optional, but should be included because it enables cross-platform and cross-language compatibility.
Table 44 - Entries in a file specification dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Required if an EF or RF entry is present; recommended always) The type of PDF object that this dictionary describes; shall be Filespec for a file specification dictionary. |
| FS | name | (Optional) The name of the file system that shall be used to interpret this file specification. If this entry is present, all other entries in the dictionary shall be interpreted by the designated file system. PDF shall define only one standard file system name, URL (see 7.11.5, "URL Specifications"); an application can register other names (see Annex E). This entry shall be independent of the F , UF , DOS , Mac , and Unix entries. |
| F | string | (Required if the DOS , Mac , and Unix entries are all absent; amended with the UF entry for PDF 1.7) A file specification string of the form described in 7.11.2, "File Specification Strings," or (if the file system is URL) a uniform resource locator, as described in 7.11.5, "URL Specifications." The UF entry should be used in addition to the F entry. The UF entry provides cross-platform and cross-language compatibility and the F entry provides backwards compatibility. |
| UF | text string | (Optional, but recommended if the F entry exists in the dictionary; PDF 1.7) A Unicode text string that provides file specification of the form described in 7.11.2, "File Specification Strings." This is a text string encoded using PDFDocEncoding or UTF-16BE with a leading byte-order marker (as defined in 7.9.2.2, "Text String Type"). The F entry should be included along with this entry for backwards compatibility reasons. |
| DOS | byte string | (Optional) A file specification string (see 7.11.2, "File Specification Strings") representing a DOS file name. This entry is obsolescent and should not be used by conforming writers. |
| Mac | byte string | (Optional) A file specification string (see 7.11.2, "File Specification Strings") representing a Mac OS file name. This entry is obsolescent and should not be used by conforming writers. |
| Unix | byte string | (Optional) A file specification string (see 7.11.2, "File Specification Strings") representing a UNIX file name. This entry is obsolescent and should not be used by conforming writers. |
Table 44 - Entries in a file specification dictionary (continued)
| Key | Type | Value |
|---|---|---|
| ID | array | (Optional) An array of two byte strings constituting a file identifier (see 14.4, "File Identifiers") that should be included in the referenced file. NOTE The use of this entry improves an application's chances of finding the intended file and allows it to warn the user if the file has changed since the link was made. |
| V | boolean | (Optional; PDF 1.2) A flag indicating whether the file referenced by the file specification is volatile (changes frequently with time). If the value is true , applications shall not cache a copy of the file. For example, a movie annotation referencing a URL to a live video camera could set this flag to true to notify the conforming reader that it should re-acquire the movie each time it is played. Default value: false . |
| EF | dictionary | (Required if RF is present; PDF 1.3; amended to include the UF key in PDF 1.7) A dictionary containing a subset of the keys F , UF , DOS , Mac , and Unix , corresponding to the entries by those names in the file specification dictionary. The value of each such key shall be an embedded file stream (see 7.11.4, "Embedded File Streams") containing the corresponding file. If this entry is present, the Type entry is required and the file specification dictionary shall be indirectly referenced. The F and UF entries should be used in place of the DOS , Mac , or Unix entries. |
| RF | dictionary | (Optional; PDF 1.3) A dictionary with the same structure as the EF dictionary, which shall be present. Each key in the RF dictionary shall also be present in the EF dictionary. Each value shall be a related files array (see 7.11.4.2, "Related Files Arrays") identifying files that are related to the corresponding file in the EF dictionary. If this entry is present, the Type entry is required and the file specification dictionary shall be indirectly referenced. |
| Desc | text string | (Optional; PDF 1.6) Descriptive text associated with the file specification. It shall be used for files in the EmbeddedFiles name tree (see 7.7.4, "Name Dictionary"). |
| CI | dictionary | ( Optional; shall be indirect reference; PDF 1.7 ) A collection item dictionary, which shall be used to create the user interface for portable collections (see 7.11.6, "Collection Items"). |
If a PDF file contains file specifications that refer to an external file and the PDF file is archived or transmitted, some provision should be made to ensure that the external references will remain valid. One way to do this is to arrange for copies of the external files to accompany the PDF file. Embedded file streams (PDF 1.3) address this problem by allowing the contents of referenced files to be embedded directly within the body of the PDF file. This makes the PDF file a self-contained unit that can be stored or transmitted as a single entity. (The embedded files are included purely for convenience and need not be directly processed by any conforming reader.)
NOTE If the file contains OPI (Open Prepress Interface) dictionaries that refer to externally stored high-resolution images (see 14.11.7, "Open Prepress Interface (OPI)"), the image data can be incorporated into the PDF file with embedded file streams.
An embedded file stream shall be included in a PDF document in one of the following ways:
- Any file specification dictionary in the document may have an EF entry that specifies an embedded file stream. The stream data shall still be associated with a location in the file system. In particular, this method
shall be used for file attachment annotations (see 12.5.6.15, "File Attachment Annotations"), which associate the embedded file with a location on a page in the document.
- Embedded file streams may be associated with the document as a whole through the EmbeddedFiles entry ( PDF 1.4 ) in the PDF document's name dictionary (see 7.7.4, "Name Dictionary"). The associated name tree shall map name strings to file specifications that refer to embedded file streams through their EF entries.
Beginning with PDF 1.6, the Desc entry of the file specification dictionary (see Table 44) should be used to provide a textual description of the embedded file, which can be displayed in the user interface of a conforming reader. Previously, it was necessary to identify document-level embedded files by the name string provided in the name dictionary associated with an embedded file stream in much the same way that the JavaScript name tree associates name strings with document-level JavaScript actions (see 12.6.4.16, "JavaScript Actions").
The stream dictionary describing an embedded file shall contain the standard entries for any stream, such as Length and Filter (see Table 5), as well as the additional entries shown in Table 45.
Table 45 - Additional entries in an embedded file stream dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | (Optional) The type of PDF object that this dictionary describes; if present, shall be EmbeddedFile for an embedded file stream. |
| Subtype | name | (Optional) The subtype of the embedded file. The value of this entry shall be a first-class name, as defined in Annex E. Names without a registered prefix shall conform to the MIME media type names defined in Internet RFC 2046, Multipurpose Internet Mail Extensions (MIME), Part Two: Media Types (see the Bibliography), with the provision that characters not allowed in names shall use the 2-character hexadecimal code format described in 7.3.5, "Name Objects." |
| Params | dictionary | (Optional) An embedded file parameter dictionary that shall contain additional file-specific information (see Table 46). |
Table 46 - Entries in an embedded file parameter dictionary
| Key | Type | Value |
|---|---|---|
| Size | integer | (Optional) The size of the uncompressed embedded file, in bytes. |
| CreationDate | date | (Optional) The date and time when the embedded file was created. |
| ModDate | date | (Optional) The date and time when the embedded file was last modified. |
| Mac | dictionary | (Optional) A subdictionary containing additional information specific to Mac OS files (see Table 47). |
| CheckSum | string | (Optional) A 16-byte string that is the checksum of the bytes of the uncompressed embedded file. The checksum shall be calculated by applying the standard MD5 message-digest algorithm (described in Internet RFC 1321, The MD5 Message-Digest Algorithm ; see the Bibliography) to the bytes of the embedded file stream. |
For Mac OS files, the Mac entry in the embedded file parameter dictionary should hold a further subdictionary containing Mac OS-specific file information. Table 47 shows the contents of this subdictionary.
Table 47 - Entries in a Mac OS file information dictionary
| Key | Type | Value |
|---|---|---|
| Subtype | integer | (Optional) The embedded file's file type. It shall be encoded as an integer according to Mac OS conventions: a 4-character ASCII text literal, that shall be a 32-bit integer, with the high-order byte first. EXAMPLE The file type 'CARO' is represented as the hexadecimal integer 4341524F, which is expressed in decimal as 1128354383. |
| Creator | integer | (Optional) The embedded file's creator signature shall be encoded in the same way as Subtype . |
| ResFork | stream | (Optional) The binary contents of the embedded file's resource fork. |
In some circumstances, a PDF file can refer to a group of related files, such as the set of five files that make up a DCS 1.0 colour-separated image. The file specification explicitly names only one of the files; the rest shall be identified by some systematic variation of that file name (such as by altering the extension). When such a file is to be embedded in a PDF file, the related files shall be embedded as well. This is accomplished by including a related files array (PDF 1.3) as the value of the RF entry in the file specification dictionary. The array shall have 2 ¥ n elements, which shall be paired in the form
[ string 1 stream 1 string 2 stream 2 … string n stream n ]
The first element of each pair shall be a string giving the name of one of the related files; the second element shall be an embedded file stream holding the file's contents.
EXAMPLE
In the following example, objects 21, 31, and 41 are embedded file streams containing the DOS file SUNSET . EPS, the Mac OS file Sunset . eps, and the UNIX file Sunset . eps, respectively. The file specification dictionary's RF entry specifies an array, object 30, identifying a set of embedded files related to the Mac OS file, forming a DCS 1.0 set. The example shows only the first two embedded file streams in the set; an actual PDF file would, of course, include all of them.
10 0 obj % File specification dictionary << /Type /Filespec /DOS ( SUNSET . EPS) /Mac ( Sunset . eps ) % Name of Mac OS file /Unix ( Sunset . eps ) /EF << /DOS 21 0 R /Mac 31 0 R % Embedded Mac OS file /Unix 41 0 R >> /RF << /Mac 30 0 R >> % Related files array for Mac OS file >> endobj 30 0 obj % Related files array for Mac OS file [ ( Sunset . eps ) 31 0 R % Includes file Sunset . eps itself ( Sunset . C ) 32 0 R ( Sunset . M ) 33 0 R ( Sunset . Y ) 34 0 R
( Sunset . K ) 35 0 R ] endobj 31 0 obj << /Type /EmbeddedFile /Length … /Filter … >> stream … Data for Sunset . eps … endstream endobj 32 0 obj << /Type /EmbeddedFile /Length … /Filter … >> stream … Data for Sunset . C … endstream endobj
When the FS entry in a file specification dictionary has the value URL , the value of the F entry in that dictionary is not a file specification string, but a uniform resource locator (URL) of the form defined in Internet RFC 1738, Uniform Resource Locators (see the Bibliography).
EXAMPLE The following example shows a URL specification. << /FS /URL /F ( ftp : / / www . beatles . com / Movies / AbbeyRoad . mov ) >>
The URL shall adhere to the character-encoding requirements specified in RFC 1738. Because 7-bit U.S. ASCII is a strict subset of PDFDocEncoding , this value shall also be considered to be in that encoding.
Beginning with PDF 1.7, a collection item dictionary shall contain the data described by the collection schema dictionary for a particular file in a collection (see 12.3.5, "Collections"). Table 48 describes the entries in a collection item dictionary.
| Key | Type | Value |
|---|---|---|
| Type | name | ( Optional ) The type of PDF object that this dictionary describes; if present, shall be CollectionItem for a collection item dictionary. |
% Embedded file stream for Mac OS file % Sunset . eps % Embedded file stream for related file % Sunset . C
Table 48 - Entries in a collection item dictionary
Table 48 - Entries in a collection item dictionary (continued)
| Key | Type | Value |
|---|---|---|
| Other keys | text string, date, number or dictionary | ( Optional ) Provides the data corresponding to the related fields in the collection dictionary. If the entry is a dictionary, then it shall be a collection subitem dictionary (see Table 49). The type of each entry shall match the type of data identified by the collection field dictionary (see Table 157) referenced by the same key in the collection schema dictionary (see Table 156). EXAMPLE If the corresponding collection field has a Subtype entry of S , then the entry is a text string. A single collection item dictionary may contain multiple entries, with one entry representing each key (see EXAMPLE 1 in 12.3.5, "Collections"). |
A collection subitem dictionary provides the data corresponding to the related fields in the collection dictionary, and it provides a means of associating a prefix string with that data value. The prefix shall be ignored by the sorting algorithm. Table 49 describes the entries in a collection subitem dictionary.
Table 49 - Entries in a collection subitem dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | ( Optional ) The type of PDF object that this dictionary describes; if present, shall be CollectionSubitem for a collection item dictionary. |
| D | text string, date, or number | ( Optional ) The data corresponding to the related entry in the collection field dictionary (see Table 157). The type of data shall match the data type identified by the corresponding collection field dictionary. Default: none. |
| P | text string | ( Optional ) A prefix string that shall be concatenated with the text string presented to the user. This entry is ignored when a conforming reader sorts the items in the collection. Default: none. |
The techniques described in this sub-clause can be used to maintain the integrity of the file specifications within a PDF file during the following types of operations:
- Updating the relevant file specification when a referenced file is renamed
- Determining the complete collection of files that are copied to a mirror site
- When creating new links to external files, discovering existing file specifications that refer to the same files and sharing them
- Finding the file specifications associated with embedded files to be packed or unpacked
- NOTE 1 It is not possible, in general, to find all file specification strings in a PDF file because there is no way to determine whether a given string is a file specification string. It is possible, however, to find all file specification dictionaries , provided that they meet the following conditions:
They are indirect objects.
They contain a Type entry whose value is the name Filespec .
-
NOTE 2 A conforming reader can locate all of the file specification dictionaries by traversing the PDF file's crossreference table (see 7.5.4, "Cross-Reference Table") and finding all dictionaries with Type keys whose value is Filespec . For this reason, all file specifications should be expressed in dictionary form and meet the conditions stated above. Any file specification dictionary specifying embedded files (that is, one that contains an EF entry) should satisfy these conditions (see Table 44).
-
NOTE 3 It may not be possible to locate file specification dictionaries that are direct objects, since they are neither selftyped nor necessarily reachable by any standard path of object references.
-
NOTE 4 Files may be embedded in a PDF file either directly, using the EF entry in a file specification dictionary, or indirectly, using related files arrays specified in the RF entry. If a file is embedded indirectly, its name is given by the string that precedes the embedded file stream in the related files array. If it is embedded directly, its name is obtained from the value of the corresponding entry in the file specification dictionary.
-
EXAMPLE The EXAMPLE in 7.11.4.2, "Related Files Arrays," for instance, shows the EF dictionary having a DOS entry identifying object number 21 as an embedded file stream. The name of the embedded DOS file, SUNSET . EPS, is given by the DOS entry in the file specification dictionary.
-
NOTE 5 A given external file may be referenced from more than one file specification. Therefore, when embedding a file with a given name, it is recommended to check for other occurrences of the same name as the value associated with the corresponding key in other file specification dictionaries. This requires finding all embeddable file specifications and, for each matching key, checking for both of the following conditions:
The string value associated with the key matches the name of the file being embedded.
A file has not already been embedded for the file specification.
- NOTE 6 If there is already a corresponding key in the EF dictionary, a file has already been embedded for that use of the file name.
- NOTE 7 Files associated with a given file name need not be unique. The same file name, such as readme . txt, may be associated with different embedded files in distinct file specifications.
The extensions dictionary, an entry in the document's catalog dictionary, if present, shall contain one or more entries identifying developer-defined extensions to the ISO 32000-1 Standard. An extensions dictionary, not shown, may optionally contain a Type entry whose value is the name Extensions . The keys in the extensions dictionary shall be names consisting only of the registered prefixes, described in Annex E, of the developers whose extensions are being used. The values shall be developer extensions dictionaries specifying developerdefined version information as shown in Table 50. The extensions dictionary, all developer extensions dictionary entries in the extensions dictionary, as well as their entries, all shall be direct objects (i.e., this information shall be nested directly within the catalog dictionary with no indirect objects used).
Table 50 describes the entries in a developer extensions dictionary.
Table 50 - Entries in a developer extensions dictionary
| Key | Type | Value |
|---|---|---|
| Type | name | ( Optional ) The type of PDF object that this dictionary describes; if present, shall be DeveloperExtensions . |
| BaseVersion | name | ( Required ) The name of the PDF version to which this extension applies. The name shall be consistent with the syntax used for the Version entry of the catalog dictionary (see 7.7.2, 'Document Catalog'). |
| ExtensionLevel | integer | ( Required ) An integer defined by the developer to denote the extension being used. If the developer introduces more than one extension to a given BaseVersion the extension level numbers assigned by that developer shall increase over time. |
The value of the BaseVersion entry shall be a name and shall be consistent with the syntax used for the Version entry value of the catalog dictionary (see 7.7.2, 'Document Catalog'). The value of BaseVersion , when treated as a version number, shall be less than or equal to the PDF version, both in the document header (see 7.5.2, 'File Header') and the catalog Version key value, if present. The value of BaseVersion may be different from the version number in the document header or that supplied by the Version key in the Catalog . This is because it reflects the version of the standard that has been extended and not the version of this particular file.
NOTE 1 The value of BaseVersion is not to be interpreted as a real number but as two integers with a PERIOD (2Eh) between them.
Navigation: PDF-Spec-07-Content-Streams | PDF-Spec-Index | Next →