mirror of
https://github.com/michaelrsweet/pdfio.git
synced 2025-07-13 06:24:25 +02:00
Save work on documentation.
This commit is contained in:
Michael R Sweet
266
doc/pdfio.3
266
doc/pdfio.3
@ -1,4 +1,4 @@
|
||||
.TH pdfio 3 "pdf read/write library" "2021-07-18" "pdf read/write library"
|
||||
.TH pdfio 3 "pdf read/write library" "2021-07-24" "pdf read/write library"
|
||||
.SH NAME
|
||||
pdfio \- pdf read/write library
|
||||
.SH Introduction
|
||||
@ -180,7 +180,7 @@ PDFio provides a primary header file that is always used:
|
||||
#include <pdfio.h>
|
||||
.fi
|
||||
.PP
|
||||
PDFio also provides helper functions for producing PDF content that are defined in a separate header file:
|
||||
PDFio also provides PDF content helper functions for producing PDF content that are defined in a separate header file:
|
||||
.nf
|
||||
|
||||
#include <pdfio\-content.h>
|
||||
@ -263,12 +263,12 @@ You create a new PDF file using the pdfioFileCreate function:
|
||||
.nf
|
||||
|
||||
pdfio_rect_t media_box = { 0.0, 0.0, 612.0, 792.0 }; // US Letter
|
||||
pdfio_rect_t crop_box = { 36.0, 36.0, 576.0, 756.0 }; // 0.5" margins
|
||||
pdfio_rect_t crop_box = { 36.0, 36.0, 576.0, 756.0 }; // w/0.5" margins
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileCreate("myoutputfile.pdf", "2.0", &media_box, &crop_box, error_cb, error_data);
|
||||
.fi
|
||||
.PP
|
||||
where the six arguments to the function are the filename ("myoutputfile.pdf"), PDF version ("2.0"), media box (media_box), crop box (crop_box), an optional error callback function (error_cb), and an optional pointer value for the error callback function (error_data).
|
||||
where the six arguments to the function are the filename ("myoutputfile.pdf"), PDF version ("2.0"), media box (media_box), crop box (crop_box), an optional error callback function (error_cb), and an optional pointer value for the error callback function (error_data). The units for the media and crop boxes are points (1/72nd of an inch).
|
||||
.PP
|
||||
Once the file is created, use the pdfioFileCreateObj, pdfioFileCreatePage, and pdfioPageCopy functions to create objects and pages in the file.
|
||||
.PP
|
||||
@ -300,7 +300,230 @@ pdfioObjGetType returns the type name of the object, for example "XObject" for a
|
||||
|
||||
|
||||
.SS PDF Streams
|
||||
.PP
|
||||
Some PDF objects have an associated data stream, such as for pages, images, ICC color profiles, and fonts. You access the stream for an existing object using the pdfioObjOpenStream function:
|
||||
.nf
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileOpen(...);
|
||||
pdfio_obj_t *obj = pdfioFileFindObj(pdf, number);
|
||||
pdfio_stream_t *st = pdfioObjOpenStream(obj, true);
|
||||
.fi
|
||||
.PP
|
||||
The first argument is the object pointer. The second argument is a boolean value that specifies whether you want to decode (typically decompress) the stream data or return it as\-is.
|
||||
.PP
|
||||
Once you have the stream open, you can use one of several functions to read from it:
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioStreamConsume reads and discards a number of bytes in the stream
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioStreamGetToken reads a PDF token from the stream
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioStreamPeek peeks at the next stream data without advancing or "consuming" it
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioStreamRead reads a buffer of data
|
||||
|
||||
|
||||
.PP
|
||||
When you are done reading from the stream, call the pdfioStreamClose function:
|
||||
.nf
|
||||
|
||||
pdfioStreamClose(st);
|
||||
.fi
|
||||
.PP
|
||||
To create a stream for a new object, call the pdfioObjCreateStream function:
|
||||
.nf
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *pdfioFileCreateObj(pdf, ...);
|
||||
pdfio_stream_t *pdfioObjCreateStream(obj, PDFIO_FILTER_FLATE);
|
||||
.fi
|
||||
.PP
|
||||
The first argument is the newly created object. The second argument is either PDFIO_FILTER_NONE to specify that any encoding is done by your program or PDFIO_FILTER_FLATE to specify that PDFio should Flate compress the stream.
|
||||
.PP
|
||||
Once you have created the stream, use any of the following functions to write to the stream:
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioStreamPrintf writes a formatted string to the stream
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioStreamPutChar writes a single character to the stream
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioStreamPuts writes a C string to the stream
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioStreamWrite writes a buffer of data to the stream
|
||||
|
||||
|
||||
.PP
|
||||
The PDF content helper functions provide additional functions for writing specific PDF page stream commands.
|
||||
.PP
|
||||
When you are done writing the stream, call pdfioStreamCLose to close both the stream and the object.
|
||||
.SS PDF Content Helper Functions
|
||||
.PP
|
||||
PDFio includes many helper functions for embedding or writing specific kinds of content to a PDF file. These functions can be roughly grouped into ??? categories:
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
Color Space Functions
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
Font Object Functions
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
Image Object Functions
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
Page Stream Functions
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
Page Dictionary Functions
|
||||
|
||||
|
||||
.PP
|
||||
Color Space Functions
|
||||
.PP
|
||||
PDF color spaces are specified using well\-known names like "DeviceCMYK", "DeviceGray", and "DeviceRGB" or using arrays that define so\-called calibrated color spaces. PDFio provides several functions for embedding ICC profiles and creating color space arrays:
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioArrayCreateColorFromICCObj creates a color array for an ICC color profile object
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioArrayCreateColorFromMatrix creates a color array using a CIE XYZ color transform matrix, a gamma value, and a CIE XYZ white point
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioArrayCreateColorFromPalette creates an indexed color array from an array of sRGB values
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
pdfioArrayCreateColorFromPrimaries creates a color array using CIE XYZ primaries and a gamma value
|
||||
|
||||
|
||||
.PP
|
||||
You can embed an ICC color profile using the pdfioFileCreateICCObjFromFile function:
|
||||
.nf
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *icc = pdfioFileCreateICCObjFromFile(pdf, "filename.icc");
|
||||
.fi
|
||||
.PP
|
||||
where the first argument is the PDF file and the second argument is the filename of the ICC color profile.
|
||||
.PP
|
||||
PDFio also includes predefined constants for creating a few standard color spaces:
|
||||
.nf
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
|
||||
// Create an AdobeRGB color array
|
||||
pdfio_array_t *adobe_rgb = pdfioArrayCreateColorFromMatrix(pdf, 3, pdfioAdobeRGBGamma, pdfioAdobeRGBMatrix, pdfioAdobeRGBWhitePoint);
|
||||
|
||||
// Create an Display P3 color array
|
||||
pdfio_array_t *display_p3 = pdfioArrayCreateColorFromMatrix(pdf, 3, pdfioDisplay P3Gamma, pdfioDisplay P3Matrix, pdfioDisplay P3WhitePoint);
|
||||
|
||||
// Create an sRGB color array
|
||||
pdfio_array_t *srgb = pdfioArrayCreateColorFromMatrix(pdf, 3, pdfioSRGBGamma, pdfioSRGBMatrix, pdfioSRGBWhitePoint);
|
||||
.fi
|
||||
.PP
|
||||
Font Object Functions
|
||||
.PP
|
||||
PDF supports many kinds of fonts, including PostScript Type1, PDF Type3, TrueType/OpenType, and CID. PDFio provides two functions for creating font objects. The first is pdfioFileCreateFontObjFromBase which creates a font object for one of the base PDF fonts:
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Courier"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Courier\-Bold"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Courier\-BoldItalic"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Courier\-Italic"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Helvetica"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Helvetica\-Bold"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Helvetica\-BoldOblique"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Helvetica\-Oblique"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Symbol"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Times\-Bold"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Times\-BoldItalic"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Times\-Italic"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"Times\-Roman"
|
||||
|
||||
.IP \(bu 5
|
||||
.PP
|
||||
"ZapfDingbats"
|
||||
|
||||
|
||||
.PP
|
||||
PDFio always uses the Windows CP1252 subset of Unicode for these fonts.
|
||||
.PP
|
||||
The second function is pdfioFileCreateFontObjFromFile which creates a font object from a TrueType/OpenType font file, for example:
|
||||
.nf
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *arial = pdfioFileCreateFontObjFromFile(pdf, "OpenSans\-Regular.ttf", false);
|
||||
.fi
|
||||
.PP
|
||||
will embed an OpenSans Regular TrueType font using the Windows CP1252 subset of Unicode. Pass true for the third argument to embed it as a Unicode CID font instead, for example:
|
||||
.nf
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *arial = pdfioFileCreateFontObjFromFile(pdf, "NotoSansJP\-Regular.otf", true);
|
||||
.fi
|
||||
.PP
|
||||
will embed the NotoSansJP Regular OpenType font with full support for Unicode.
|
||||
.PP
|
||||
Note: Not all fonts support Unicode.
|
||||
.PP
|
||||
Image Object Functions
|
||||
.PP
|
||||
Page Dictionary Functions
|
||||
.PP
|
||||
Page Stream Functions
|
||||
|
||||
.SH ENUMERATIONS
|
||||
.SS pdfio_filter_e
|
||||
@ -1511,33 +1734,33 @@ This function creates one of the base 14 PDF fonts. The "name" parameter
|
||||
specifies the font nane:
|
||||
.PP
|
||||
.IP \(bu 5
|
||||
\fBCourier\fR
|
||||
"Courier"
|
||||
.IP \(bu 5
|
||||
\fBCourier-Bold\fR
|
||||
"Courier-Bold"
|
||||
.IP \(bu 5
|
||||
\fBCourier-BoldItalic\fR
|
||||
"Courier-BoldItalic"
|
||||
.IP \(bu 5
|
||||
\fBCourier-Italic\fR
|
||||
"Courier-Italic"
|
||||
.IP \(bu 5
|
||||
\fBHelvetica\fR
|
||||
"Helvetica"
|
||||
.IP \(bu 5
|
||||
\fBHelvetica-Bold\fR
|
||||
"Helvetica-Bold"
|
||||
.IP \(bu 5
|
||||
\fBHelvetica-BoldOblique\fR
|
||||
"Helvetica-BoldOblique"
|
||||
.IP \(bu 5
|
||||
\fBHelvetica-Oblique\fR
|
||||
"Helvetica-Oblique"
|
||||
.IP \(bu 5
|
||||
\fBSymbol\fR
|
||||
"Symbol"
|
||||
.IP \(bu 5
|
||||
\fBTimes-Bold\fR
|
||||
"Times-Bold"
|
||||
.IP \(bu 5
|
||||
\fBTimes-BoldItalic\fR
|
||||
"Times-BoldItalic"
|
||||
.IP \(bu 5
|
||||
\fBTimes-Italic\fR
|
||||
"Times-Italic"
|
||||
.IP \(bu 5
|
||||
\fBTimes-Roman\fR
|
||||
"Times-Roman"
|
||||
.IP \(bu 5
|
||||
\fBZapfDingbats\fR
|
||||
"ZapfDingbats"
|
||||
.PP
|
||||
Base fonts always use the Windows CP1252 (ISO-8859-1 with additional
|
||||
characters such as the Euro symbol) subset of Unicode.
|
||||
@ -2206,13 +2429,6 @@ PDF value types
|
||||
.nf
|
||||
typedef enum pdfio_valtype_e pdfio_valtype_t;
|
||||
.fi
|
||||
.SH VARIABLES
|
||||
.SS PDFIO_PUBLIC
|
||||
C++ magic...
|
||||
.PP
|
||||
.nf
|
||||
pdfio_dict_t *dict const char *name pdfio_obj_t *obj)PDFIO_PUBLIC;
|
||||
.fi
|
||||
.SH AUTHOR
|
||||
.PP
|
||||
Michael R Sweet
|
||||
|
||||
200
doc/pdfio.html
200
doc/pdfio.html
@ -1,13 +1,13 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en-US">
|
||||
<head>
|
||||
<title>PDFio Programming Manual v0.2</title>
|
||||
<title>PDFio Programming Manual v1.0b1</title>
|
||||
<meta http-equiv="Content-Type" content="text/html;charset=utf-8">
|
||||
<meta name="generator" content="codedoc v3.7">
|
||||
<meta name="author" content="Michael R Sweet">
|
||||
<meta name="language" content="en-US">
|
||||
<meta name="copyright" content="Copyright © 2021 by Michael R Sweet">
|
||||
<meta name="version" content="0.2">
|
||||
<meta name="version" content="1.0b1">
|
||||
<style type="text/css"><!--
|
||||
body {
|
||||
background: white;
|
||||
@ -245,7 +245,7 @@ span.string {
|
||||
<body>
|
||||
<div class="header">
|
||||
<p><img class="title" src="pdfio-512.png"></p>
|
||||
<h1 class="title">PDFio Programming Manual v0.2</h1>
|
||||
<h1 class="title">PDFio Programming Manual v1.0b1</h1>
|
||||
<p>Michael R Sweet</p>
|
||||
<p>Copyright © 2021 by Michael R Sweet</p>
|
||||
</div>
|
||||
@ -451,9 +451,6 @@ span.string {
|
||||
<li><a href="#STRUCTURES">Structures</a><ul class="subcontents">
|
||||
<li><a href="#pdfio_rect_s">pdfio_rect_s</a></li>
|
||||
</ul></li>
|
||||
<li><a href="#VARIABLES">Variables</a><ul class="subcontents">
|
||||
<li><a href="#PDFIO_PUBLIC">PDFIO_PUBLIC</a></li>
|
||||
</ul></li>
|
||||
<li><a href="#ENUMERATIONS">Enumerations</a><ul class="subcontents">
|
||||
<li><a href="#pdfio_filter_e">pdfio_filter_e</a></li>
|
||||
<li><a href="#pdfio_linecap_e">pdfio_linecap_e</a></li>
|
||||
@ -562,7 +559,7 @@ LIBS += `pkg-config --libs pdfio`
|
||||
<p>PDFio provides a primary header file that is always used:</p>
|
||||
<pre><code class="language-c"><span class="directive">#include <pdfio.h></span>
|
||||
</code></pre>
|
||||
<p>PDFio also provides helper functions for producing PDF content that are defined in a separate header file:</p>
|
||||
<p>PDFio also provides <a href="#pdf-content-helper-functions">PDF content helper functions</a> for producing PDF content that are defined in a separate header file:</p>
|
||||
<pre><code class="language-c"><span class="directive">#include <pdfio-content.h></span>
|
||||
</code></pre>
|
||||
<h2 class="title" id="api-overview">API Overview</h2>
|
||||
@ -580,7 +577,7 @@ LIBS += `pkg-config --libs pdfio`
|
||||
</li>
|
||||
</ul>
|
||||
<h3 class="title" id="reading-pdf-files">Reading PDF Files</h3>
|
||||
<p>You open an existing PDF file using the <code>pdfioFileOpen</code> function:</p>
|
||||
<p>You open an existing PDF file using the <a href="#pdfioFileOpen"><code>pdfioFileOpen</code></a> function:</p>
|
||||
<pre><code class="language-c">pdfio_file_t *pdf = pdfioFileOpen(<span class="string">"myinputfile.pdf"</span>, error_cb, error_data);
|
||||
</code></pre>
|
||||
<p>where the three arguments to the function are the filename ("myinputfile.pdf"), an optional error callback function (<code>error_cb</code>), and an optional pointer value for the error callback function (<code>error_data</code>). The error callback is called for both errors and warnings and accepts the <code>pdfio_file_t</code> pointer, a message string, and the callback pointer value, for example:</p>
|
||||
@ -596,7 +593,7 @@ error_cb(pdfio_file_t *pdf, <span class="reserved">const</span> <span class="res
|
||||
}
|
||||
</code></pre>
|
||||
<p>The default error callback (<code>NULL</code>) does the equivalent of the above.</p>
|
||||
<p>Each PDF file contains one or more pages. The <code>pdfioFileGetNumPages</code> function returns the number of pages in the file while the <code>pdfioFileGetPage</code> function gets the specified page in the PDF file:</p>
|
||||
<p>Each PDF file contains one or more pages. The <a href="#pdfioFileGetNumPages"><code>pdfioFileGetNumPages</code></a> function returns the number of pages in the file while the <a href="#pdfioFileGetPage"><code>pdfioFileGetPage</code></a> function gets the specified page in the PDF file:</p>
|
||||
<pre><code class="language-c">pdfio_file_t *pdf; <span class="comment">// PDF file</span>
|
||||
size_t i; <span class="comment">// Looping var</span>
|
||||
size_t count; <span class="comment">// Number of pages</span>
|
||||
@ -609,37 +606,164 @@ pdfio_obj_t *page; <span class="comment">// Current page</span>
|
||||
<span class="comment">// do something with page</span>
|
||||
}
|
||||
</code></pre>
|
||||
<p>Each page is represented by a "page tree" object (what <code>pdfioFileGetPage</code> returns) that specifies information about the page and one or more "content" objects that contain the images, fonts, text, and graphics that appear on the page.</p>
|
||||
<p>The <code>pdfioFileClose</code> function closes a PDF file and frees all memory that was used for it:</p>
|
||||
<p>Each page is represented by a "page tree" object (what <a href="#pdfioFileGetPage"><code>pdfioFileGetPage</code></a> returns) that specifies information about the page and one or more "content" objects that contain the images, fonts, text, and graphics that appear on the page.</p>
|
||||
<p>The <a href="#pdfioFileClose"><code>pdfioFileClose</code></a> function closes a PDF file and frees all memory that was used for it:</p>
|
||||
<pre><code class="language-c">pdfioFileClose(pdf);
|
||||
</code></pre>
|
||||
<h3 class="title" id="writing-pdf-files">Writing PDF Files</h3>
|
||||
<p>You create a new PDF file using the <code>pdfioFileCreate</code> function:</p>
|
||||
<p>You create a new PDF file using the <a href="#pdfioFileCreate"><code>pdfioFileCreate</code></a> function:</p>
|
||||
<pre><code class="language-c">pdfio_rect_t media_box = { <span class="number">0.0</span>, <span class="number">0.0</span>, <span class="number">612.0</span>, <span class="number">792.0</span> }; <span class="comment">// US Letter</span>
|
||||
pdfio_rect_t crop_box = { <span class="number">36.0</span>, <span class="number">36.0</span>, <span class="number">576.0</span>, <span class="number">756.0</span> }; <span class="comment">// 0.5" margins</span>
|
||||
pdfio_rect_t crop_box = { <span class="number">36.0</span>, <span class="number">36.0</span>, <span class="number">576.0</span>, <span class="number">756.0</span> }; <span class="comment">// w/0.5" margins</span>
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileCreate(<span class="string">"myoutputfile.pdf"</span>, <span class="string">"2.0"</span>, &media_box, &crop_box, error_cb, error_data);
|
||||
</code></pre>
|
||||
<p>where the six arguments to the function are the filename ("myoutputfile.pdf"), PDF version ("2.0"), media box (<code>media_box</code>), crop box (<code>crop_box</code>), an optional error callback function (<code>error_cb</code>), and an optional pointer value for the error callback function (<code>error_data</code>).</p>
|
||||
<p>Once the file is created, use the <code>pdfioFileCreateObj</code>, <code>pdfioFileCreatePage</code>, and <code>pdfioPageCopy</code> functions to create objects and pages in the file.</p>
|
||||
<p>Finally, the <code>pdfioFileClose</code> function writes the PDF cross-reference and "trailer" information, closes the file, and frees all memory that was used for it.</p>
|
||||
<p>where the six arguments to the function are the filename ("myoutputfile.pdf"), PDF version ("2.0"), media box (<code>media_box</code>), crop box (<code>crop_box</code>), an optional error callback function (<code>error_cb</code>), and an optional pointer value for the error callback function (<code>error_data</code>). The units for the media and crop boxes are points (1/72nd of an inch).</p>
|
||||
<p>Once the file is created, use the <a href="#pdfioFileCreateObj"><code>pdfioFileCreateObj</code></a>, <a href="#pdfioFileCreatePage"><code>pdfioFileCreatePage</code></a>, and <a href="#pdfioPageCopy"><code>pdfioPageCopy</code></a> functions to create objects and pages in the file.</p>
|
||||
<p>Finally, the <a href="#pdfioFileClose"><code>pdfioFileClose</code></a> function writes the PDF cross-reference and "trailer" information, closes the file, and frees all memory that was used for it.</p>
|
||||
<h3 class="title" id="pdf-objects">PDF Objects</h3>
|
||||
<p>PDF objects are identified using two numbers - the object number (1 to N) and the object generation (0 to 65535) that specifies a particular version of an object. An object's numbers are returned by the <code>pdfioObjGetNumber</code> and <code>pdfioObjGetGeneration</code> functions. You can find a numbered object using the <code>pdfioFileFindObj</code> function.</p>
|
||||
<p>PDF objects are identified using two numbers - the object number (1 to N) and the object generation (0 to 65535) that specifies a particular version of an object. An object's numbers are returned by the <a href="#pdfioObjGetNumber"><code>pdfioObjGetNumber</code></a> and <a href="#pdfioObjGetGeneration"><code>pdfioObjGetGeneration</code></a> functions. You can find a numbered object using the <a href="#pdfioFileFindObj"><code>pdfioFileFindObj</code></a> function.</p>
|
||||
<p>Objects contain values (typically dictionaries) and usually an associated data stream containing images, fonts, ICC profiles, and page content. PDFio provides several accessor functions to get the value(s) associated with an object:</p>
|
||||
<ul>
|
||||
<li><p><code>pdfioObjGetArray</code> returns an object's array value, if any</p>
|
||||
<li><p><a href="#pdfioObjGetArray"><code>pdfioObjGetArray</code></a> returns an object's array value, if any</p>
|
||||
</li>
|
||||
<li><p><code>pdfioObjGetDict</code> returns an object's dictionary value, if any</p>
|
||||
<li><p><a href="#pdfioObjGetDict"><code>pdfioObjGetDict</code></a> returns an object's dictionary value, if any</p>
|
||||
</li>
|
||||
<li><p><code>pdfioObjGetLength</code> returns the length of the data stream, if any</p>
|
||||
<li><p><a href="#pdfioObjGetLength"><code>pdfioObjGetLength</code></a> returns the length of the data stream, if any</p>
|
||||
</li>
|
||||
<li><p><code>pdfioObjGetSubtype</code> returns the sub-type name of the object, for example "Image" for an image object.</p>
|
||||
<li><p><a href="#pdfioObjGetSubtype"><code>pdfioObjGetSubtype</code></a> returns the sub-type name of the object, for example "Image" for an image object.</p>
|
||||
</li>
|
||||
<li><p><code>pdfioObjGetType</code> returns the type name of the object, for example "XObject" for an image object.</p>
|
||||
<li><p><a href="#pdfioObjGetType"><code>pdfioObjGetType</code></a> returns the type name of the object, for example "XObject" for an image object.</p>
|
||||
</li>
|
||||
</ul>
|
||||
<h3 class="title" id="pdf-streams">PDF Streams</h3>
|
||||
<p>Some PDF objects have an associated data stream, such as for pages, images, ICC color profiles, and fonts. You access the stream for an existing object using the <a href="#pdfioObjOpenStream"><code>pdfioObjOpenStream</code></a> function:</p>
|
||||
<pre><code class="language-c">pdfio_file_t *pdf = pdfioFileOpen(...);
|
||||
pdfio_obj_t *obj = pdfioFileFindObj(pdf, number);
|
||||
pdfio_stream_t *st = pdfioObjOpenStream(obj, <span class="reserved">true</span>);
|
||||
</code></pre>
|
||||
<p>The first argument is the object pointer. The second argument is a boolean value that specifies whether you want to decode (typically decompress) the stream data or return it as-is.</p>
|
||||
<p>Once you have the stream open, you can use one of several functions to read from it:</p>
|
||||
<ul>
|
||||
<li><p><a href="#pdfioStreamConsume"><code>pdfioStreamConsume</code></a> reads and discards a number of bytes in the stream</p>
|
||||
</li>
|
||||
<li><p><a href="#pdfioStreamGetToken"><code>pdfioStreamGetToken</code></a> reads a PDF token from the stream</p>
|
||||
</li>
|
||||
<li><p><a href="#pdfioStreamPeek"><code>pdfioStreamPeek</code></a> peeks at the next stream data without advancing or "consuming" it</p>
|
||||
</li>
|
||||
<li><p><a href="#pdfioStreamRead"><code>pdfioStreamRead</code></a> reads a buffer of data</p>
|
||||
</li>
|
||||
</ul>
|
||||
<p>When you are done reading from the stream, call the <a href="#pdfioStreamClose"><code>pdfioStreamClose</code></a> function:</p>
|
||||
<pre><code class="language-c">pdfioStreamClose(st);
|
||||
</code></pre>
|
||||
<p>To create a stream for a new object, call the <a href="#pdfioObjCreateStream"><code>pdfioObjCreateStream</code></a> function:</p>
|
||||
<pre><code class="language-c">pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *pdfioFileCreateObj(pdf, ...);
|
||||
pdfio_stream_t *pdfioObjCreateStream(obj, PDFIO_FILTER_FLATE);
|
||||
</code></pre>
|
||||
<p>The first argument is the newly created object. The second argument is either <code>PDFIO_FILTER_NONE</code> to specify that any encoding is done by your program or <code>PDFIO_FILTER_FLATE</code> to specify that PDFio should Flate compress the stream.</p>
|
||||
<p>Once you have created the stream, use any of the following functions to write to the stream:</p>
|
||||
<ul>
|
||||
<li><p><a href="#pdfioStreamPrintf"><code>pdfioStreamPrintf</code></a> writes a formatted string to the stream</p>
|
||||
</li>
|
||||
<li><p><a href="#pdfioStreamPutChar"><code>pdfioStreamPutChar</code></a> writes a single character to the stream</p>
|
||||
</li>
|
||||
<li><p><a href="#pdfioStreamPuts"><code>pdfioStreamPuts</code></a> writes a C string to the stream</p>
|
||||
</li>
|
||||
<li><p><a href="#pdfioStreamWrite"><code>pdfioStreamWrite</code></a> writes a buffer of data to the stream</p>
|
||||
</li>
|
||||
</ul>
|
||||
<p>The <a href="#pdf-content-helper-functions">PDF content helper functions</a> provide additional functions for writing specific PDF page stream commands.</p>
|
||||
<p>When you are done writing the stream, call <a href="#pdfioStreamCLose"><code>pdfioStreamCLose</code></a> to close both the stream and the object.</p>
|
||||
<h3 class="title" id="pdf-content-helper-functions">PDF Content Helper Functions</h3>
|
||||
<p>PDFio includes many helper functions for embedding or writing specific kinds of content to a PDF file. These functions can be roughly grouped into ??? categories:</p>
|
||||
<ul>
|
||||
<li><p><a href="#color-space-functions">Color Space Functions</a></p>
|
||||
</li>
|
||||
<li><p><a href="#font-object-functions">Font Object Functions</a></p>
|
||||
</li>
|
||||
<li><p><a href="#image-object-functions">Image Object Functions</a></p>
|
||||
</li>
|
||||
<li><p><a href="#page-stream-functions">Page Stream Functions</a></p>
|
||||
</li>
|
||||
<li><p><a href="#page-dictionary-functions">Page Dictionary Functions</a></p>
|
||||
</li>
|
||||
</ul>
|
||||
<h4 id="color-space-functions">Color Space Functions</h4>
|
||||
<p>PDF color spaces are specified using well-known names like "DeviceCMYK", "DeviceGray", and "DeviceRGB" or using arrays that define so-called calibrated color spaces. PDFio provides several functions for embedding ICC profiles and creating color space arrays:</p>
|
||||
<ul>
|
||||
<li><p><a href="#pdfioArrayCreateColorFromICCObj"><code>pdfioArrayCreateColorFromICCObj</code></a> creates a color array for an ICC color profile object</p>
|
||||
</li>
|
||||
<li><p><a href="#pdfioArrayCreateColorFromMatrix"><code>pdfioArrayCreateColorFromMatrix</code></a> creates a color array using a CIE XYZ color transform matrix, a gamma value, and a CIE XYZ white point</p>
|
||||
</li>
|
||||
<li><p><a href="#pdfioArrayCreateColorFromPalette"><code>pdfioArrayCreateColorFromPalette</code></a> creates an indexed color array from an array of sRGB values</p>
|
||||
</li>
|
||||
<li><p><a href="#pdfioArrayCreateColorFromPrimaries"><code>pdfioArrayCreateColorFromPrimaries</code></a> creates a color array using CIE XYZ primaries and a gamma value</p>
|
||||
</li>
|
||||
</ul>
|
||||
<p>You can embed an ICC color profile using the <a href="#pdfioFileCreateICCObjFromFile"><code>pdfioFileCreateICCObjFromFile</code></a> function:</p>
|
||||
<pre><code class="language-c">pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *icc = pdfioFileCreateICCObjFromFile(pdf, <span class="string">"filename.icc"</span>);
|
||||
</code></pre>
|
||||
<p>where the first argument is the PDF file and the second argument is the filename of the ICC color profile.</p>
|
||||
<p>PDFio also includes predefined constants for creating a few standard color spaces:</p>
|
||||
<pre><code class="language-c">pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
|
||||
<span class="comment">// Create an AdobeRGB color array</span>
|
||||
pdfio_array_t *adobe_rgb = pdfioArrayCreateColorFromMatrix(pdf, <span class="number">3</span>, pdfioAdobeRGBGamma, pdfioAdobeRGBMatrix, pdfioAdobeRGBWhitePoint);
|
||||
|
||||
<span class="comment">// Create an Display P3 color array</span>
|
||||
pdfio_array_t *display_p3 = pdfioArrayCreateColorFromMatrix(pdf, <span class="number">3</span>, pdfioDisplay P3Gamma, pdfioDisplay P3Matrix, pdfioDisplay P3WhitePoint);
|
||||
|
||||
<span class="comment">// Create an sRGB color array</span>
|
||||
pdfio_array_t *srgb = pdfioArrayCreateColorFromMatrix(pdf, <span class="number">3</span>, pdfioSRGBGamma, pdfioSRGBMatrix, pdfioSRGBWhitePoint);
|
||||
</code></pre>
|
||||
<h4 id="font-object-functions">Font Object Functions</h4>
|
||||
<p>PDF supports many kinds of fonts, including PostScript Type1, PDF Type3, TrueType/OpenType, and CID. PDFio provides two functions for creating font objects. The first is <a href="#pdfioFileCreateFontObjFromBase"><code>pdfioFileCreateFontObjFromBase</code></a> which creates a font object for one of the base PDF fonts:</p>
|
||||
<ul>
|
||||
<li><p>"Courier"</p>
|
||||
</li>
|
||||
<li><p>"Courier-Bold"</p>
|
||||
</li>
|
||||
<li><p>"Courier-BoldItalic"</p>
|
||||
</li>
|
||||
<li><p>"Courier-Italic"</p>
|
||||
</li>
|
||||
<li><p>"Helvetica"</p>
|
||||
</li>
|
||||
<li><p>"Helvetica-Bold"</p>
|
||||
</li>
|
||||
<li><p>"Helvetica-BoldOblique"</p>
|
||||
</li>
|
||||
<li><p>"Helvetica-Oblique"</p>
|
||||
</li>
|
||||
<li><p>"Symbol"</p>
|
||||
</li>
|
||||
<li><p>"Times-Bold"</p>
|
||||
</li>
|
||||
<li><p>"Times-BoldItalic"</p>
|
||||
</li>
|
||||
<li><p>"Times-Italic"</p>
|
||||
</li>
|
||||
<li><p>"Times-Roman"</p>
|
||||
</li>
|
||||
<li><p>"ZapfDingbats"</p>
|
||||
</li>
|
||||
</ul>
|
||||
<p>PDFio always uses the Windows CP1252 subset of Unicode for these fonts.</p>
|
||||
<p>The second function is <a href="#pdfioFileCreateFontObjFromFile"><code>pdfioFileCreateFontObjFromFile</code></a> which creates a font object from a TrueType/OpenType font file, for example:</p>
|
||||
<pre><code class="language-c">pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *arial = pdfioFileCreateFontObjFromFile(pdf, <span class="string">"OpenSans-Regular.ttf"</span>, <span class="reserved">false</span>);
|
||||
</code></pre>
|
||||
<p>will embed an OpenSans Regular TrueType font using the Windows CP1252 subset of Unicode. Pass <code>true</code> for the third argument to embed it as a Unicode CID font instead, for example:</p>
|
||||
<pre><code class="language-c">pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *arial = pdfioFileCreateFontObjFromFile(pdf, <span class="string">"NotoSansJP-Regular.otf"</span>, <span class="reserved">true</span>);
|
||||
</code></pre>
|
||||
<p>will embed the NotoSansJP Regular OpenType font with full support for Unicode.</p>
|
||||
<p>Note: Not all fonts support Unicode.</p>
|
||||
<h4 id="image-object-functions">Image Object Functions</h4>
|
||||
<h4 id="page-dictionary-functions">Page Dictionary Functions</h4>
|
||||
<h4 id="page-stream-functions">Page Stream Functions</h4>
|
||||
<h2 class="title"><a id="FUNCTIONS">Functions</a></h2>
|
||||
<h3 class="function"><a id="pdfioArrayAppendArray">pdfioArrayAppendArray</a></h3>
|
||||
<p class="description">Add an array value to an array.</p>
|
||||
@ -2195,33 +2319,33 @@ You must call <a href="#pdfioObjClose"><code>pdfioObjClose</code></a> to write t
|
||||
specifies the font nane:
|
||||
|
||||
</p><ul>
|
||||
<li><code>Courier</code>
|
||||
<li>"Courier"
|
||||
</li>
|
||||
<li><code>Courier-Bold</code>
|
||||
<li>"Courier-Bold"
|
||||
</li>
|
||||
<li><code>Courier-BoldItalic</code>
|
||||
<li>"Courier-BoldItalic"
|
||||
</li>
|
||||
<li><code>Courier-Italic</code>
|
||||
<li>"Courier-Italic"
|
||||
</li>
|
||||
<li><code>Helvetica</code>
|
||||
<li>"Helvetica"
|
||||
</li>
|
||||
<li><code>Helvetica-Bold</code>
|
||||
<li>"Helvetica-Bold"
|
||||
</li>
|
||||
<li><code>Helvetica-BoldOblique</code>
|
||||
<li>"Helvetica-BoldOblique"
|
||||
</li>
|
||||
<li><code>Helvetica-Oblique</code>
|
||||
<li>"Helvetica-Oblique"
|
||||
</li>
|
||||
<li><code>Symbol</code>
|
||||
<li>"Symbol"
|
||||
</li>
|
||||
<li><code>Times-Bold</code>
|
||||
<li>"Times-Bold"
|
||||
</li>
|
||||
<li><code>Times-BoldItalic</code>
|
||||
<li>"Times-BoldItalic"
|
||||
</li>
|
||||
<li><code>Times-Italic</code>
|
||||
<li>"Times-Italic"
|
||||
</li>
|
||||
<li><code>Times-Roman</code>
|
||||
<li>"Times-Roman"
|
||||
</li>
|
||||
<li><code>ZapfDingbats</code></li>
|
||||
<li>"ZapfDingbats"</li>
|
||||
</ul>
|
||||
<p class="discussion">Base fonts always use the Windows CP1252 (ISO-8859-1 with additional
|
||||
characters such as the Euro symbol) subset of Unicode.</p>
|
||||
@ -3093,10 +3217,6 @@ typedef enum <a href="#pdfio_valtype_e">pdfio_valtype_e</a> pdfio_valtype_t;
|
||||
<tr><th>y2 </th>
|
||||
<td class="description">Upper-right Y coordinate</td></tr>
|
||||
</tbody></table>
|
||||
<h2 class="title"><a id="VARIABLES">Variables</a></h2>
|
||||
<h3 class="variable"><a id="PDFIO_PUBLIC">PDFIO_PUBLIC</a></h3>
|
||||
<p class="description">C++ magic...</p>
|
||||
<p class="code"><a href="#pdfio_dict_t">pdfio_dict_t</a> *dict const char *name <a href="#pdfio_obj_t">pdfio_obj_t</a> *obj) PDFIO_PUBLIC;</p>
|
||||
<h2 class="title"><a id="ENUMERATIONS">Constants</a></h2>
|
||||
<h3 class="enumeration"><a id="pdfio_filter_e">pdfio_filter_e</a></h3>
|
||||
<p class="description">Compression/decompression filters for streams</p>
|
||||
|
||||
215
doc/pdfio.md
215
doc/pdfio.md
@ -135,8 +135,8 @@ PDFio provides a primary header file that is always used:
|
||||
#include <pdfio.h>
|
||||
```
|
||||
|
||||
PDFio also provides helper functions for producing PDF content that are defined
|
||||
in a separate header file:
|
||||
PDFio also provides [PDF content helper functions](@) for producing PDF content
|
||||
that are defined in a separate header file:
|
||||
|
||||
```c
|
||||
#include <pdfio-content.h>
|
||||
@ -158,7 +158,7 @@ PDFio exposes several types:
|
||||
Reading PDF Files
|
||||
-----------------
|
||||
|
||||
You open an existing PDF file using the `pdfioFileOpen` function:
|
||||
You open an existing PDF file using the [`pdfioFileOpen`](@@) function:
|
||||
|
||||
```c
|
||||
pdfio_file_t *pdf = pdfioFileOpen("myinputfile.pdf", error_cb, error_data);
|
||||
@ -186,9 +186,9 @@ error_cb(pdfio_file_t *pdf, const char *message, void *data)
|
||||
|
||||
The default error callback (`NULL`) does the equivalent of the above.
|
||||
|
||||
Each PDF file contains one or more pages. The `pdfioFileGetNumPages` function
|
||||
returns the number of pages in the file while the `pdfioFileGetPage` function
|
||||
gets the specified page in the PDF file:
|
||||
Each PDF file contains one or more pages. The [`pdfioFileGetNumPages`](@@)
|
||||
function returns the number of pages in the file while the
|
||||
[`pdfioFileGetPage`](@@) function gets the specified page in the PDF file:
|
||||
|
||||
```c
|
||||
pdfio_file_t *pdf; // PDF file
|
||||
@ -204,26 +204,27 @@ for (i = 0, count = pdfioFileGetNumPages(pdf); i < count; i ++)
|
||||
}
|
||||
```
|
||||
|
||||
Each page is represented by a "page tree" object (what `pdfioFileGetPage`
|
||||
Each page is represented by a "page tree" object (what [`pdfioFileGetPage`](@@)
|
||||
returns) that specifies information about the page and one or more "content"
|
||||
objects that contain the images, fonts, text, and graphics that appear on the
|
||||
page.
|
||||
|
||||
The `pdfioFileClose` function closes a PDF file and frees all memory that was
|
||||
used for it:
|
||||
The [`pdfioFileClose`](@@) function closes a PDF file and frees all memory that
|
||||
was used for it:
|
||||
|
||||
```c
|
||||
pdfioFileClose(pdf);
|
||||
```
|
||||
|
||||
|
||||
Writing PDF Files
|
||||
-----------------
|
||||
|
||||
You create a new PDF file using the `pdfioFileCreate` function:
|
||||
You create a new PDF file using the [`pdfioFileCreate`](@@) function:
|
||||
|
||||
```c
|
||||
pdfio_rect_t media_box = { 0.0, 0.0, 612.0, 792.0 }; // US Letter
|
||||
pdfio_rect_t crop_box = { 36.0, 36.0, 576.0, 756.0 }; // 0.5" margins
|
||||
pdfio_rect_t crop_box = { 36.0, 36.0, 576.0, 756.0 }; // w/0.5" margins
|
||||
|
||||
pdfio_file_t *pdf = pdfioFileCreate("myoutputfile.pdf", "2.0", &media_box, &crop_box, error_cb, error_data);
|
||||
```
|
||||
@ -231,12 +232,14 @@ pdfio_file_t *pdf = pdfioFileCreate("myoutputfile.pdf", "2.0", &media_box, &crop
|
||||
where the six arguments to the function are the filename ("myoutputfile.pdf"),
|
||||
PDF version ("2.0"), media box (`media_box`), crop box (`crop_box`), an optional
|
||||
error callback function (`error_cb`), and an optional pointer value for the
|
||||
error callback function (`error_data`).
|
||||
error callback function (`error_data`). The units for the media and crop boxes
|
||||
are points (1/72nd of an inch).
|
||||
|
||||
Once the file is created, use the `pdfioFileCreateObj`, `pdfioFileCreatePage`,
|
||||
and `pdfioPageCopy` functions to create objects and pages in the file.
|
||||
Once the file is created, use the [`pdfioFileCreateObj`](@@),
|
||||
[`pdfioFileCreatePage`](@@), and [`pdfioPageCopy`](@@) functions to create
|
||||
objects and pages in the file.
|
||||
|
||||
Finally, the `pdfioFileClose` function writes the PDF cross-reference and
|
||||
Finally, the [`pdfioFileClose`](@@) function writes the PDF cross-reference and
|
||||
"trailer" information, closes the file, and frees all memory that was used for
|
||||
it.
|
||||
|
||||
@ -246,26 +249,188 @@ PDF Objects
|
||||
|
||||
PDF objects are identified using two numbers - the object number (1 to N) and
|
||||
the object generation (0 to 65535) that specifies a particular version of an
|
||||
object. An object's numbers are returned by the `pdfioObjGetNumber` and
|
||||
`pdfioObjGetGeneration` functions. You can find a numbered object using the
|
||||
`pdfioFileFindObj` function.
|
||||
object. An object's numbers are returned by the [`pdfioObjGetNumber`](@@) and
|
||||
[`pdfioObjGetGeneration`](@@) functions. You can find a numbered object using
|
||||
the [`pdfioFileFindObj`](@@) function.
|
||||
|
||||
Objects contain values (typically dictionaries) and usually an associated data
|
||||
stream containing images, fonts, ICC profiles, and page content. PDFio provides several accessor functions to get the value(s) associated with an object:
|
||||
|
||||
- `pdfioObjGetArray` returns an object's array value, if any
|
||||
- `pdfioObjGetDict` returns an object's dictionary value, if any
|
||||
- `pdfioObjGetLength` returns the length of the data stream, if any
|
||||
- `pdfioObjGetSubtype` returns the sub-type name of the object, for example
|
||||
"Image" for an image object.
|
||||
- `pdfioObjGetType` returns the type name of the object, for example "XObject"
|
||||
for an image object.
|
||||
- [`pdfioObjGetArray`](@@) returns an object's array value, if any
|
||||
- [`pdfioObjGetDict`](@@) returns an object's dictionary value, if any
|
||||
- [`pdfioObjGetLength`](@@) returns the length of the data stream, if any
|
||||
- [`pdfioObjGetSubtype`](@@) returns the sub-type name of the object, for
|
||||
example "Image" for an image object.
|
||||
- [`pdfioObjGetType`](@@) returns the type name of the object, for example
|
||||
"XObject" for an image object.
|
||||
|
||||
|
||||
PDF Streams
|
||||
-----------
|
||||
|
||||
Some PDF objects have an associated data stream, such as for pages, images, ICC
|
||||
color profiles, and fonts. You access the stream for an existing object using
|
||||
the [`pdfioObjOpenStream`](@@) function:
|
||||
|
||||
```c
|
||||
pdfio_file_t *pdf = pdfioFileOpen(...);
|
||||
pdfio_obj_t *obj = pdfioFileFindObj(pdf, number);
|
||||
pdfio_stream_t *st = pdfioObjOpenStream(obj, true);
|
||||
```
|
||||
|
||||
The first argument is the object pointer. The second argument is a boolean
|
||||
value that specifies whether you want to decode (typically decompress) the
|
||||
stream data or return it as-is.
|
||||
|
||||
Once you have the stream open, you can use one of several functions to read
|
||||
from it:
|
||||
|
||||
- [`pdfioStreamConsume`](@@) reads and discards a number of bytes in the stream
|
||||
- [`pdfioStreamGetToken`](@@) reads a PDF token from the stream
|
||||
- [`pdfioStreamPeek`](@@) peeks at the next stream data without advancing or
|
||||
"consuming" it
|
||||
- [`pdfioStreamRead`](@@) reads a buffer of data
|
||||
|
||||
When you are done reading from the stream, call the [`pdfioStreamClose`](@@)
|
||||
function:
|
||||
|
||||
```c
|
||||
pdfioStreamClose(st);
|
||||
```
|
||||
|
||||
To create a stream for a new object, call the [`pdfioObjCreateStream`](@@)
|
||||
function:
|
||||
|
||||
```c
|
||||
pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *pdfioFileCreateObj(pdf, ...);
|
||||
pdfio_stream_t *pdfioObjCreateStream(obj, PDFIO_FILTER_FLATE);
|
||||
```
|
||||
|
||||
The first argument is the newly created object. The second argument is either
|
||||
`PDFIO_FILTER_NONE` to specify that any encoding is done by your program or
|
||||
`PDFIO_FILTER_FLATE` to specify that PDFio should Flate compress the stream.
|
||||
|
||||
Once you have created the stream, use any of the following functions to write
|
||||
to the stream:
|
||||
|
||||
- [`pdfioStreamPrintf`](@@) writes a formatted string to the stream
|
||||
- [`pdfioStreamPutChar`](@@) writes a single character to the stream
|
||||
- [`pdfioStreamPuts`](@@) writes a C string to the stream
|
||||
- [`pdfioStreamWrite`](@@) writes a buffer of data to the stream
|
||||
|
||||
The [PDF content helper functions](@) provide additional functions for writing
|
||||
specific PDF page stream commands.
|
||||
|
||||
When you are done writing the stream, call [`pdfioStreamCLose`](@@) to close
|
||||
both the stream and the object.
|
||||
|
||||
|
||||
PDF Content Helper Functions
|
||||
----------------------------
|
||||
|
||||
PDFio includes many helper functions for embedding or writing specific kinds of
|
||||
content to a PDF file. These functions can be roughly grouped into ???
|
||||
categories:
|
||||
|
||||
- [Color Space Functions](@)
|
||||
- [Font Object Functions](@)
|
||||
- [Image Object Functions](@)
|
||||
- [Page Stream Functions](@)
|
||||
- [Page Dictionary Functions](@)
|
||||
|
||||
|
||||
### Color Space Functions
|
||||
|
||||
PDF color spaces are specified using well-known names like "DeviceCMYK",
|
||||
"DeviceGray", and "DeviceRGB" or using arrays that define so-called calibrated
|
||||
color spaces. PDFio provides several functions for embedding ICC profiles and
|
||||
creating color space arrays:
|
||||
|
||||
- [`pdfioArrayCreateColorFromICCObj`](@@) creates a color array for an ICC color profile object
|
||||
- [`pdfioArrayCreateColorFromMatrix`](@@) creates a color array using a CIE XYZ color transform matrix, a gamma value, and a CIE XYZ white point
|
||||
- [`pdfioArrayCreateColorFromPalette`](@@) creates an indexed color array from an array of sRGB values
|
||||
- [`pdfioArrayCreateColorFromPrimaries`](@@) creates a color array using CIE XYZ primaries and a gamma value
|
||||
|
||||
You can embed an ICC color profile using the
|
||||
[`pdfioFileCreateICCObjFromFile`](@@) function:
|
||||
|
||||
```c
|
||||
pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *icc = pdfioFileCreateICCObjFromFile(pdf, "filename.icc");
|
||||
```
|
||||
|
||||
where the first argument is the PDF file and the second argument is the filename
|
||||
of the ICC color profile.
|
||||
|
||||
PDFio also includes predefined constants for creating a few standard color
|
||||
spaces:
|
||||
|
||||
```c
|
||||
pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
|
||||
// Create an AdobeRGB color array
|
||||
pdfio_array_t *adobe_rgb = pdfioArrayCreateColorFromMatrix(pdf, 3, pdfioAdobeRGBGamma, pdfioAdobeRGBMatrix, pdfioAdobeRGBWhitePoint);
|
||||
|
||||
// Create an Display P3 color array
|
||||
pdfio_array_t *display_p3 = pdfioArrayCreateColorFromMatrix(pdf, 3, pdfioDisplay P3Gamma, pdfioDisplay P3Matrix, pdfioDisplay P3WhitePoint);
|
||||
|
||||
// Create an sRGB color array
|
||||
pdfio_array_t *srgb = pdfioArrayCreateColorFromMatrix(pdf, 3, pdfioSRGBGamma, pdfioSRGBMatrix, pdfioSRGBWhitePoint);
|
||||
```
|
||||
|
||||
|
||||
### Font Object Functions
|
||||
|
||||
PDF supports many kinds of fonts, including PostScript Type1, PDF Type3,
|
||||
TrueType/OpenType, and CID. PDFio provides two functions for creating font
|
||||
objects. The first is [`pdfioFileCreateFontObjFromBase`](@@) which creates a
|
||||
font object for one of the base PDF fonts:
|
||||
|
||||
- "Courier"
|
||||
- "Courier-Bold"
|
||||
- "Courier-BoldItalic"
|
||||
- "Courier-Italic"
|
||||
- "Helvetica"
|
||||
- "Helvetica-Bold"
|
||||
- "Helvetica-BoldOblique"
|
||||
- "Helvetica-Oblique"
|
||||
- "Symbol"
|
||||
- "Times-Bold"
|
||||
- "Times-BoldItalic"
|
||||
- "Times-Italic"
|
||||
- "Times-Roman"
|
||||
- "ZapfDingbats"
|
||||
|
||||
PDFio always uses the Windows CP1252 subset of Unicode for these fonts.
|
||||
|
||||
The second function is [`pdfioFileCreateFontObjFromFile`](@@) which creates a
|
||||
font object from a TrueType/OpenType font file, for example:
|
||||
|
||||
```c
|
||||
pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *arial = pdfioFileCreateFontObjFromFile(pdf, "OpenSans-Regular.ttf", false);
|
||||
```
|
||||
|
||||
will embed an OpenSans Regular TrueType font using the Windows CP1252 subset of
|
||||
Unicode. Pass `true` for the third argument to embed it as a Unicode CID font
|
||||
instead, for example:
|
||||
|
||||
```c
|
||||
pdfio_file_t *pdf = pdfioFileCreate(...);
|
||||
pdfio_obj_t *arial = pdfioFileCreateFontObjFromFile(pdf, "NotoSansJP-Regular.otf", true);
|
||||
```
|
||||
|
||||
will embed the NotoSansJP Regular OpenType font with full support for Unicode.
|
||||
|
||||
Note: Not all fonts support Unicode.
|
||||
|
||||
|
||||
### Image Object Functions
|
||||
|
||||
|
||||
### Page Dictionary Functions
|
||||
|
||||
|
||||
### Page Stream Functions
|
||||
|
||||
|
||||
Reference in New Issue
Block a user