dany/pdfio
1
0
Fork 0
mirror of https://github.com/michaelrsweet/pdfio.git synced 2026-04-09 13:32:31 +02:00
Code Issues Packages Projects Releases Wiki Activity

Update documentation to mention GIF files (Issue #145)

Browse Source
This commit is contained in:
Michael R Sweet
2026-01-18 11:43:56 -05:00
parent c2f2cd6c37
commit 61d7e0c68d
6 changed files with 73 additions and 134 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
CHANGES.md
View File

@@ -9,6 +9,7 @@ v1.7.0 - YYYY-MM-DD
- Added support for basic compound stream filters for ASCII85Decode support - Added support for basic compound stream filters for ASCII85Decode support
(Issue #11) (Issue #11)
- Added support for LZWDecode filters (Issue #11) - Added support for LZWDecode filters (Issue #11)
- Added support for GIF files (Issue #145)
- Added `pdfioPageGetXxx` functions to get values from the page dictionaries - Added `pdfioPageGetXxx` functions to get values from the page dictionaries
(Issue #150) (Issue #150)
- Fixed a buffer overflow in the (still not enabled) AES-256 code. - Fixed a buffer overflow in the (still not enabled) AES-256 code.

62
doc/pdfio.3
View File

@@ -1,4 +1,4 @@
.TH pdfio 3 "pdf read/write library" "2026-01-16" "pdf read/write library" .TH pdfio 3 "pdf read/write library" "2026-01-18" "pdf read/write library"
.SH NAME .SH NAME
pdfio \- pdf read/write library pdfio \- pdf read/write library
.SH Introduction .SH Introduction
@@ -34,7 +34,7 @@ PDFio is
.I not .I not
concerned with rendering or viewing a PDF file, although a PDF RIP or viewer could be written using it. concerned with rendering or viewing a PDF file, although a PDF RIP or viewer could be written using it.
.PP .PP
PDFio is Copyright \[co] 2021\-2025 by Michael R Sweet and is licensed under the Apache License Version 2.0 with an (optional) exception to allow linking against GPL2/LGPL2 software. See the files "LICENSE" and "NOTICE" for more information. PDFio is Copyright \[co] 2021\-2026 by Michael R Sweet and is licensed under the Apache License Version 2.0 with an (optional) exception to allow linking against GPL2/LGPL2 software. See the files "LICENSE" and "NOTICE" for more information.
.SS Requirements .SS Requirements
.PP .PP
PDFio requires the following to build the software: PDFio requires the following to build the software:
@@ -361,41 +361,28 @@ Each PDF file contains one or more pages. The pdfioFileGetNumPages function retu
} }
.fi .fi
.PP .PP
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. Use the pdfioPageGetNumStreams and pdfioPageOpenStream functions to access the content streams for each page, and pdfioObjGetDict to get the associated page object dictionary. For example, if you want to display the media and crop boxes for a given page: 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. Use the pdfioPageGetNumStreams and pdfioPageOpenStream functions to access the content streams for each page, pdfioObjGetDict to get the associated page object dictionary, and pdfioPageGetArray, pdfioPageGetBinary, pdfioPageGetBoolean, pdfioPageGetDate, pdfioPageGetDict, pdfioPageGetName, pdfioPageGetObj, pdfioPageGetRect, and pdfioPageGetString to get a value from the page object dictionary or its parents. For example, if you want to display the media and crop boxes for a given page:
.nf .nf
pdfio_file_t *pdf; // PDF file pdfio_file_t *pdf; // PDF file
size_t i; // Looping var size_t i; // Looping var
size_t count; // Number of pages size_t count; // Number of pages
pdfio_obj_t *page; // Current page pdfio_obj_t *page; // Current page
pdfio_dict_t *dict; // Current page dictionary pdfio_rect_t media_box; // MediaBox values
pdfio_array_t *media_box; // MediaBox array pdfio_rect_t crop_box; // CropBox values
double media_values[4]; // MediaBox values
pdfio_array_t *crop_box; // CropBox array
double crop_values[4]; // CropBox values
// Iterate the pages in the PDF file // Iterate the pages in the PDF file
for (i = 0, count = pdfioFileGetNumPages(pdf); i < count; i ++) for (i = 0, count = pdfioFileGetNumPages(pdf); i < count; i ++)
{ {
page = pdfioFileGetPage(pdf, i); page = pdfioFileGetPage(pdf, i);
dict = pdfioObjGetDict(page);
media_box = pdfioDictGetArray(dict, "MediaBox"); pdfioPageGetRect(page, "MediaBox", &media_box);
media_values[0] = pdfioArrayGetNumber(media_box, 0); pdfioPageGetRect(page, "CropBox", &crop_box);
media_values[1] = pdfioArrayGetNumber(media_box, 1);
media_values[2] = pdfioArrayGetNumber(media_box, 2);
media_values[3] = pdfioArrayGetNumber(media_box, 3);
crop_box = pdfioDictGetArray(dict, "CropBox");
crop_values[0] = pdfioArrayGetNumber(crop_box, 0);
crop_values[1] = pdfioArrayGetNumber(crop_box, 1);
crop_values[2] = pdfioArrayGetNumber(crop_box, 2);
crop_values[3] = pdfioArrayGetNumber(crop_box, 3);
printf("Page %u: MediaBox=[%g %g %g %g], CropBox=[%g %g %g %g]\\n", printf("Page %u: MediaBox=[%g %g %g %g], CropBox=[%g %g %g %g]\\n",
(unsigned)(i + 1), (unsigned)(i + 1),
media_values[0], media_values[1], media_values[2], media_values[3], media_box.x1, media_box.y1, media_box.x2, media_box.y2,
crop_values[0], crop_values[1], crop_values[2], crop_values[3]); crop_box.x1, crop_box.y1, crop_box.x2, crop_box.y2);
} }
.fi .fi
.PP .PP
@@ -784,16 +771,13 @@ will create an object for a 1024x1024 RGBA image in memory, using the default co
.PP .PP
The "interpolate" argument specifies whether the colors in the image should be smoothed/interpolated when scaling. This is most useful for photographs but should be false for screenshot and barcode images. The "interpolate" argument specifies whether the colors in the image should be smoothed/interpolated when scaling. This is most useful for photographs but should be false for screenshot and barcode images.
.PP .PP
If you have a JPEG or PNG file, use the pdfioFileCreateImageObjFromFile function to copy the image into a PDF image object, for example: If you have a GIF, JPEG, or PNG file, use the pdfioFileCreateImageObjFromFile function to copy the image into a PDF image object, for example:
.nf .nf
pdfio_file_t *pdf = pdfioFileCreate(...); pdfio_file_t *pdf = pdfioFileCreate(...);
pdfio_obj_t *img = pdfio_obj_t *img =
pdfioFileCreateImageObjFromFile(pdf, "myphoto.jpg", /*interpolate*/true); pdfioFileCreateImageObjFromFile(pdf, "myphoto.jpg", /*interpolate*/true);
.fi .fi
.PP
Note: Currently pdfioFileCreateImageObjFromFile does not support 12 bit JPEG files or PNG files with an alpha channel.
.PP .PP
Page Dictionary Functions Page Dictionary Functions
.PP .PP
@@ -1176,16 +1160,10 @@ The pdfioinfo.c example program opens a PDF file and prints the title, author, c
for (cur = 0, prev = 0; cur < num_pages; cur ++) for (cur = 0, prev = 0; cur < num_pages; cur ++)
{ {
// Find the MediaBox for this page in the page tree... // Find the MediaBox for this page in the page tree...
for (page = pdfioFileGetPage(pdf, cur); page = pdfioFileGetPage(pdf, cur);
page != NULL;
page = pdfioDictGetObj(page_dict, "Parent"))
{
cur_box.x1 = cur_box.x2 = cur_box.y1 = cur_box.y2 = 0.0;
page_dict = pdfioObjGetDict(page);
if (pdfioDictGetRect(page_dict, "MediaBox", &cur_box)) cur_box.x1 = cur_box.x2 = cur_box.y1 = cur_box.y2 = 0.0;
break; pdfioPageGetRect(page, "MediaBox", &cur_box);
}
// If this MediaBox is different from the previous one, show the range of // If this MediaBox is different from the previous one, show the range of
// pages that have that size... // pages that have that size...
@@ -1458,7 +1436,7 @@ Then we loop through the differences array, keeping track of the current index w
.fi .fi
.SS Create a PDF File With Text and an Image .SS Create a PDF File With Text and an Image
.PP .PP
The image2pdf.c example code creates a PDF file containing a JPEG or PNG image file and optional caption on a single page. The create_pdf_image_file function creates the PDF file, embeds a base font and the named JPEG or PNG image file, and then creates a page with the image centered on the page with any text centered below: The image2pdf.c example code creates a PDF file containing a GIF, JPEG, or PNG image file and optional caption on a single page. The create_pdf_image_file function creates the PDF file, embeds a base font and the named JPEG or PNG image file, and then creates a page with the image centered on the page with any text centered below:
.nf .nf
#include <pdfio.h> #include <pdfio.h>
@@ -4209,15 +4187,17 @@ pdfio_obj_t * pdfioFileCreateImageObjFromFile (
); );
.fi .fi
.PP .PP
This function creates an image object in a PDF file from a JPEG or PNG file. This function creates an image object in a PDF file from a GIF, JPEG, or PNG
The "filename" parameter specifies the name of the JPEG or PNG file, while file. The "filename" parameter specifies the name of the GIF, JPEG, or PNG
the "interpolate" parameter specifies whether to interpolate when scaling the file, while the "interpolate" parameter specifies whether to interpolate when
image on the page. scaling the image on the page.
.PP .PP
.IP 5 .IP 5
Note: PNG files containing transparency cannot be used when producing Note: PNG files containing transparency cannot be used when producing
.IP 5 .IP 5
PDF/A files. PDF/A files. Files containing animation yield the final frame of the
.IP 5
animation.
.SS pdfioFileCreateNameObj .SS pdfioFileCreateNameObj
Create a new object in a PDF file containing a name. Create a new object in a PDF file containing a name.
.PP .PP

59
doc/pdfio.html
View File

@@ -560,7 +560,7 @@ span.string {
</li> </li>
</ul> </ul>
<p>PDFio is <em>not</em> concerned with rendering or viewing a PDF file, although a PDF RIP or viewer could be written using it.</p> <p>PDFio is <em>not</em> concerned with rendering or viewing a PDF file, although a PDF RIP or viewer could be written using it.</p>
<p>PDFio is Copyright © 2021-2025 by Michael R Sweet and is licensed under the Apache License Version 2.0 with an (optional) exception to allow linking against GPL2/LGPL2 software. See the files &quot;LICENSE&quot; and &quot;NOTICE&quot; for more information.</p> <p>PDFio is Copyright © 2021-2026 by Michael R Sweet and is licensed under the Apache License Version 2.0 with an (optional) exception to allow linking against GPL2/LGPL2 software. See the files &quot;LICENSE&quot; and &quot;NOTICE&quot; for more information.</p>
<h3 class="title" id="requirements">Requirements</h3> <h3 class="title" id="requirements">Requirements</h3>
<p>PDFio requires the following to build the software:</p> <p>PDFio requires the following to build the software:</p>
<ul> <ul>
@@ -792,39 +792,26 @@ pdfio_obj_t *page; <span class="comment">// Current page</span>
<span class="comment">// do something with page</span> <span class="comment">// do something with page</span>
} }
</code></pre> </code></pre>
<p>Each page is represented by a &quot;page tree&quot; object (what <a href="#pdfioFileGetPage"><code>pdfioFileGetPage</code></a> returns) that specifies information about the page and one or more &quot;content&quot; objects that contain the images, fonts, text, and graphics that appear on the page. Use the <a href="#pdfioPageGetNumStreams"><code>pdfioPageGetNumStreams</code></a> and <a href="#pdfioPageOpenStream"><code>pdfioPageOpenStream</code></a> functions to access the content streams for each page, and <a href="#pdfioObjGetDict"><code>pdfioObjGetDict</code></a> to get the associated page object dictionary. For example, if you want to display the media and crop boxes for a given page:</p> <p>Each page is represented by a &quot;page tree&quot; object (what <a href="#pdfioFileGetPage"><code>pdfioFileGetPage</code></a> returns) that specifies information about the page and one or more &quot;content&quot; objects that contain the images, fonts, text, and graphics that appear on the page. Use the <a href="#pdfioPageGetNumStreams"><code>pdfioPageGetNumStreams</code></a> and <a href="#pdfioPageOpenStream"><code>pdfioPageOpenStream</code></a> functions to access the content streams for each page, <a href="#pdfioObjGetDict"><code>pdfioObjGetDict</code></a> to get the associated page object dictionary, and <a href="#pdfioPageGetArray"><code>pdfioPageGetArray</code></a>, <a href="#pdfioPageGetBinary"><code>pdfioPageGetBinary</code></a>, <a href="#pdfioPageGetBoolean"><code>pdfioPageGetBoolean</code></a>, <a href="#pdfioPageGetDate"><code>pdfioPageGetDate</code></a>, <a href="#pdfioPageGetDict"><code>pdfioPageGetDict</code></a>, <a href="#pdfioPageGetName"><code>pdfioPageGetName</code></a>, <a href="#pdfioPageGetObj"><code>pdfioPageGetObj</code></a>, <a href="#pdfioPageGetRect"><code>pdfioPageGetRect</code></a>, and <a href="#pdfioPageGetString"><code>pdfioPageGetString</code></a> to get a value from the page object dictionary or its parents. For example, if you want to display the media and crop boxes for a given page:</p>
<pre><code class="language-c">pdfio_file_t *pdf; <span class="comment">// PDF file</span> <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 i; <span class="comment">// Looping var</span>
size_t count; <span class="comment">// Number of pages</span> size_t count; <span class="comment">// Number of pages</span>
pdfio_obj_t *page; <span class="comment">// Current page</span> pdfio_obj_t *page; <span class="comment">// Current page</span>
pdfio_dict_t *dict; <span class="comment">// Current page dictionary</span> pdfio_rect_t media_box; <span class="comment">// MediaBox values</span>
pdfio_array_t *media_box; <span class="comment">// MediaBox array</span> pdfio_rect_t crop_box; <span class="comment">// CropBox values</span>
<span class="reserved">double</span> media_values[<span class="number">4</span>]; <span class="comment">// MediaBox values</span>
pdfio_array_t *crop_box; <span class="comment">// CropBox array</span>
<span class="reserved">double</span> crop_values[<span class="number">4</span>]; <span class="comment">// CropBox values</span>
<span class="comment">// Iterate the pages in the PDF file</span> <span class="comment">// Iterate the pages in the PDF file</span>
<span class="reserved">for</span> (i = <span class="number">0</span>, count = pdfioFileGetNumPages(pdf); i &lt; count; i ++) <span class="reserved">for</span> (i = <span class="number">0</span>, count = pdfioFileGetNumPages(pdf); i &lt; count; i ++)
{ {
page = pdfioFileGetPage(pdf, i); page = pdfioFileGetPage(pdf, i);
dict = pdfioObjGetDict(page);
media_box = pdfioDictGetArray(dict, <span class="string">&quot;MediaBox&quot;</span>); pdfioPageGetRect(page, <span class="string">&quot;MediaBox&quot;</span>, &amp;media_box);
media_values[<span class="number">0</span>] = pdfioArrayGetNumber(media_box, <span class="number">0</span>); pdfioPageGetRect(page, <span class="string">&quot;CropBox&quot;</span>, &amp;crop_box);
media_values[<span class="number">1</span>] = pdfioArrayGetNumber(media_box, <span class="number">1</span>);
media_values[<span class="number">2</span>] = pdfioArrayGetNumber(media_box, <span class="number">2</span>);
media_values[<span class="number">3</span>] = pdfioArrayGetNumber(media_box, <span class="number">3</span>);
crop_box = pdfioDictGetArray(dict, <span class="string">&quot;CropBox&quot;</span>);
crop_values[<span class="number">0</span>] = pdfioArrayGetNumber(crop_box, <span class="number">0</span>);
crop_values[<span class="number">1</span>] = pdfioArrayGetNumber(crop_box, <span class="number">1</span>);
crop_values[<span class="number">2</span>] = pdfioArrayGetNumber(crop_box, <span class="number">2</span>);
crop_values[<span class="number">3</span>] = pdfioArrayGetNumber(crop_box, <span class="number">3</span>);
printf(<span class="string">&quot;Page %u: MediaBox=[%g %g %g %g], CropBox=[%g %g %g %g]\n&quot;</span>, printf(<span class="string">&quot;Page %u: MediaBox=[%g %g %g %g], CropBox=[%g %g %g %g]\n&quot;</span>,
(<span class="reserved">unsigned</span>)(i + <span class="number">1</span>), (<span class="reserved">unsigned</span>)(i + <span class="number">1</span>),
media_values[<span class="number">0</span>], media_values[<span class="number">1</span>], media_values[<span class="number">2</span>], media_values[<span class="number">3</span>], media_box.x1, media_box.y1, media_box.x2, media_box.y2,
crop_values[<span class="number">0</span>], crop_values[<span class="number">1</span>], crop_values[<span class="number">2</span>], crop_values[<span class="number">3</span>]); crop_box.x1, crop_box.y1, crop_box.x2, crop_box.y2);
} }
</code></pre> </code></pre>
<p>Page object dictionaries have several (mostly optional) key/value pairs, including:</p> <p>Page object dictionaries have several (mostly optional) key/value pairs, including:</p>
@@ -1059,14 +1046,11 @@ pdfio_obj_t *img =
<span class="comment">/*alpha*/</span><span class="reserved">true</span>, <span class="comment">/*interpolate*/</span><span class="reserved">false</span>); <span class="comment">/*alpha*/</span><span class="reserved">true</span>, <span class="comment">/*interpolate*/</span><span class="reserved">false</span>);
</code></pre> </code></pre>
<p>The &quot;interpolate&quot; argument specifies whether the colors in the image should be smoothed/interpolated when scaling. This is most useful for photographs but should be <code>false</code> for screenshot and barcode images.</p> <p>The &quot;interpolate&quot; argument specifies whether the colors in the image should be smoothed/interpolated when scaling. This is most useful for photographs but should be <code>false</code> for screenshot and barcode images.</p>
<p>If you have a JPEG or PNG file, use the <a href="#pdfioFileCreateImageObjFromFile"><code>pdfioFileCreateImageObjFromFile</code></a> function to copy the image into a PDF image object, for example:</p> <p>If you have a GIF, JPEG, or PNG file, use the <a href="#pdfioFileCreateImageObjFromFile"><code>pdfioFileCreateImageObjFromFile</code></a> function to copy the image into a PDF image object, for example:</p>
<pre><code class="language-c">pdfio_file_t *pdf = pdfioFileCreate(...); <pre><code class="language-c">pdfio_file_t *pdf = pdfioFileCreate(...);
pdfio_obj_t *img = pdfio_obj_t *img =
pdfioFileCreateImageObjFromFile(pdf, <span class="string">&quot;myphoto.jpg&quot;</span>, <span class="comment">/*interpolate*/</span><span class="reserved">true</span>); pdfioFileCreateImageObjFromFile(pdf, <span class="string">&quot;myphoto.jpg&quot;</span>, <span class="comment">/*interpolate*/</span><span class="reserved">true</span>);
</code></pre> </code></pre>
<blockquote>
<p>Note: Currently <code>pdfioFileCreateImageObjFromFile</code> does not support 12 bit JPEG files or PNG files with an alpha channel.</p>
</blockquote>
<h4 id="page-dictionary-functions">Page Dictionary Functions</h4> <h4 id="page-dictionary-functions">Page Dictionary Functions</h4>
<p>PDF pages each have an associated dictionary to specify the images, fonts, and color spaces used by the page. PDFio provides functions to add these resources to the dictionary:</p> <p>PDF pages each have an associated dictionary to specify the images, fonts, and color spaces used by the page. PDFio provides functions to add these resources to the dictionary:</p>
<ul> <ul>
@@ -1322,16 +1306,10 @@ main(<span class="reserved">int</span> argc, <span clas
<span class="reserved">for</span> (cur = <span class="number">0</span>, prev = <span class="number">0</span>; cur &lt; num_pages; cur ++) <span class="reserved">for</span> (cur = <span class="number">0</span>, prev = <span class="number">0</span>; cur &lt; num_pages; cur ++)
{ {
<span class="comment">// Find the MediaBox for this page in the page tree...</span> <span class="comment">// Find the MediaBox for this page in the page tree...</span>
<span class="reserved">for</span> (page = pdfioFileGetPage(pdf, cur); page = pdfioFileGetPage(pdf, cur);
page != NULL;
page = pdfioDictGetObj(page_dict, <span class="string">&quot;Parent&quot;</span>))
{
cur_box.x1 = cur_box.x2 = cur_box.y1 = cur_box.y2 = <span class="number">0.0</span>;
page_dict = pdfioObjGetDict(page);
<span class="reserved">if</span> (pdfioDictGetRect(page_dict, <span class="string">&quot;MediaBox&quot;</span>, &amp;cur_box)) cur_box.x1 = cur_box.x2 = cur_box.y1 = cur_box.y2 = <span class="number">0.0</span>;
<span class="reserved">break</span>; pdfioPageGetRect(page, <span class="string">&quot;MediaBox&quot;</span>, &amp;cur_box);
}
<span class="comment">// If this MediaBox is different from the previous one, show the range of</span> <span class="comment">// If this MediaBox is different from the previous one, show the range of</span>
<span class="comment">// pages that have that size...</span> <span class="comment">// pages that have that size...</span>
@@ -1570,7 +1548,7 @@ load_encoding(
} }
</code></pre> </code></pre>
<h3 class="title" id="create-a-pdf-file-with-text-and-an-image">Create a PDF File With Text and an Image</h3> <h3 class="title" id="create-a-pdf-file-with-text-and-an-image">Create a PDF File With Text and an Image</h3>
<p>The <code>image2pdf.c</code> example code creates a PDF file containing a JPEG or PNG image file and optional caption on a single page. The <code>create_pdf_image_file</code> function creates the PDF file, embeds a base font and the named JPEG or PNG image file, and then creates a page with the image centered on the page with any text centered below:</p> <p>The <code>image2pdf.c</code> example code creates a PDF file containing a GIF, JPEG, or PNG image file and optional caption on a single page. The <code>create_pdf_image_file</code> function creates the PDF file, embeds a base font and the named JPEG or PNG image file, and then creates a page with the image centered on the page with any text centered below:</p>
<pre><code class="language-c"><span class="directive">#include &lt;pdfio.h&gt;</span> <pre><code class="language-c"><span class="directive">#include &lt;pdfio.h&gt;</span>
<span class="directive">#include &lt;pdfio-content.h&gt;</span> <span class="directive">#include &lt;pdfio-content.h&gt;</span>
<span class="directive">#include &lt;string.h&gt;</span> <span class="directive">#include &lt;string.h&gt;</span>
@@ -4502,14 +4480,15 @@ files do not support alpha-based transparency.</blockquote>
<h4 class="returnvalue">Return Value</h4> <h4 class="returnvalue">Return Value</h4>
<p class="description">Object</p> <p class="description">Object</p>
<h4 class="discussion">Discussion</h4> <h4 class="discussion">Discussion</h4>
<p class="discussion">This function creates an image object in a PDF file from a JPEG or PNG file. <p class="discussion">This function creates an image object in a PDF file from a GIF, JPEG, or PNG
The &quot;filename&quot; parameter specifies the name of the JPEG or PNG file, while file. The &quot;filename&quot; parameter specifies the name of the GIF, JPEG, or PNG
the &quot;interpolate&quot; parameter specifies whether to interpolate when scaling the file, while the &quot;interpolate&quot; parameter specifies whether to interpolate when
image on the page.<br> scaling the image on the page.<br>
<br> <br>
</p><blockquote> </p><blockquote>
Note: PNG files containing transparency cannot be used when producing Note: PNG files containing transparency cannot be used when producing
PDF/A files.</blockquote> PDF/A files. Files containing animation yield the final frame of the
animation.</blockquote>
<h3 class="function"><span class="info">&#160;PDFio v1.4&#160;</span><a id="pdfioFileCreateNameObj">pdfioFileCreateNameObj</a></h3> <h3 class="function"><span class="info">&#160;PDFio v1.4&#160;</span><a id="pdfioFileCreateNameObj">pdfioFileCreateNameObj</a></h3>
<p class="description">Create a new object in a PDF file containing a name.</p> <p class="description">Create a new object in a PDF file containing a name.</p>
<p class="code"> <p class="code">

60
doc/pdfio.md
View File

@@ -15,7 +15,7 @@ goals of PDFio are:
PDFio is *not* concerned with rendering or viewing a PDF file, although a PDF PDFio is *not* concerned with rendering or viewing a PDF file, although a PDF
RIP or viewer could be written using it. RIP or viewer could be written using it.
PDFio is Copyright © 2021-2025 by Michael R Sweet and is licensed under the PDFio is Copyright © 2021-2026 by Michael R Sweet and is licensed under the
Apache License Version 2.0 with an (optional) exception to allow linking against Apache License Version 2.0 with an (optional) exception to allow linking against
GPL2/LGPL2 software. See the files "LICENSE" and "NOTICE" for more information. GPL2/LGPL2 software. See the files "LICENSE" and "NOTICE" for more information.
@@ -387,43 +387,35 @@ Each page is represented by a "page tree" object (what [`pdfioFileGetPage`](@@)
returns) that specifies information about the page and one or more "content" 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 objects that contain the images, fonts, text, and graphics that appear on the
page. Use the [`pdfioPageGetNumStreams`](@@) and [`pdfioPageOpenStream`](@@) page. Use the [`pdfioPageGetNumStreams`](@@) and [`pdfioPageOpenStream`](@@)
functions to access the content streams for each page, and functions to access the content streams for each page, [`pdfioObjGetDict`](@@)
[`pdfioObjGetDict`](@@) to get the associated page object dictionary. For to get the associated page object dictionary, and [`pdfioPageGetArray`](@@),
example, if you want to display the media and crop boxes for a given page: [`pdfioPageGetBinary`](@@), [`pdfioPageGetBoolean`](@@),
[`pdfioPageGetDate`](@@), [`pdfioPageGetDict`](@@), [`pdfioPageGetName`](@@),
[`pdfioPageGetObj`](@@), [`pdfioPageGetRect`](@@), and
[`pdfioPageGetString`](@@) to get a value from the page object dictionary or its
parents. For example, if you want to display the media and crop boxes for a
given page:
```c ```c
pdfio_file_t *pdf; // PDF file pdfio_file_t *pdf; // PDF file
size_t i; // Looping var size_t i; // Looping var
size_t count; // Number of pages size_t count; // Number of pages
pdfio_obj_t *page; // Current page pdfio_obj_t *page; // Current page
pdfio_dict_t *dict; // Current page dictionary pdfio_rect_t media_box; // MediaBox values
pdfio_array_t *media_box; // MediaBox array pdfio_rect_t crop_box; // CropBox values
double media_values[4]; // MediaBox values
pdfio_array_t *crop_box; // CropBox array
double crop_values[4]; // CropBox values
// Iterate the pages in the PDF file // Iterate the pages in the PDF file
for (i = 0, count = pdfioFileGetNumPages(pdf); i < count; i ++) for (i = 0, count = pdfioFileGetNumPages(pdf); i < count; i ++)
{ {
page = pdfioFileGetPage(pdf, i); page = pdfioFileGetPage(pdf, i);
dict = pdfioObjGetDict(page);
media_box = pdfioDictGetArray(dict, "MediaBox"); pdfioPageGetRect(page, "MediaBox", &media_box);
media_values[0] = pdfioArrayGetNumber(media_box, 0); pdfioPageGetRect(page, "CropBox", &crop_box);
media_values[1] = pdfioArrayGetNumber(media_box, 1);
media_values[2] = pdfioArrayGetNumber(media_box, 2);
media_values[3] = pdfioArrayGetNumber(media_box, 3);
crop_box = pdfioDictGetArray(dict, "CropBox");
crop_values[0] = pdfioArrayGetNumber(crop_box, 0);
crop_values[1] = pdfioArrayGetNumber(crop_box, 1);
crop_values[2] = pdfioArrayGetNumber(crop_box, 2);
crop_values[3] = pdfioArrayGetNumber(crop_box, 3);
printf("Page %u: MediaBox=[%g %g %g %g], CropBox=[%g %g %g %g]\n", printf("Page %u: MediaBox=[%g %g %g %g], CropBox=[%g %g %g %g]\n",
(unsigned)(i + 1), (unsigned)(i + 1),
media_values[0], media_values[1], media_values[2], media_values[3], media_box.x1, media_box.y1, media_box.x2, media_box.y2,
crop_values[0], crop_values[1], crop_values[2], crop_values[3]); crop_box.x1, crop_box.y1, crop_box.x2, crop_box.y2);
} }
``` ```
@@ -760,8 +752,9 @@ The "interpolate" argument specifies whether the colors in the image should be
smoothed/interpolated when scaling. This is most useful for photographs but smoothed/interpolated when scaling. This is most useful for photographs but
should be `false` for screenshot and barcode images. should be `false` for screenshot and barcode images.
If you have a JPEG or PNG file, use the [`pdfioFileCreateImageObjFromFile`](@@) If you have a GIF, JPEG, or PNG file, use the
function to copy the image into a PDF image object, for example: [`pdfioFileCreateImageObjFromFile`](@@) function to copy the image into a PDF
image object, for example:
```c ```c
pdfio_file_t *pdf = pdfioFileCreate(...); pdfio_file_t *pdf = pdfioFileCreate(...);
@@ -769,9 +762,6 @@ pdfio_obj_t *img =
pdfioFileCreateImageObjFromFile(pdf, "myphoto.jpg", /*interpolate*/true); pdfioFileCreateImageObjFromFile(pdf, "myphoto.jpg", /*interpolate*/true);
``` ```
> Note: Currently `pdfioFileCreateImageObjFromFile` does not support 12 bit JPEG
> files or PNG files with an alpha channel.
### Page Dictionary Functions ### Page Dictionary Functions
@@ -1029,16 +1019,10 @@ main(int argc, // I - Number of command-line arguments
for (cur = 0, prev = 0; cur < num_pages; cur ++) for (cur = 0, prev = 0; cur < num_pages; cur ++)
{ {
// Find the MediaBox for this page in the page tree... // Find the MediaBox for this page in the page tree...
for (page = pdfioFileGetPage(pdf, cur); page = pdfioFileGetPage(pdf, cur);
page != NULL;
page = pdfioDictGetObj(page_dict, "Parent"))
{
cur_box.x1 = cur_box.x2 = cur_box.y1 = cur_box.y2 = 0.0;
page_dict = pdfioObjGetDict(page);
if (pdfioDictGetRect(page_dict, "MediaBox", &cur_box)) cur_box.x1 = cur_box.x2 = cur_box.y1 = cur_box.y2 = 0.0;
break; pdfioPageGetRect(page, "MediaBox", &cur_box);
}
// If this MediaBox is different from the previous one, show the range of // If this MediaBox is different from the previous one, show the range of
// pages that have that size... // pages that have that size...
@@ -1342,7 +1326,7 @@ Unicode glyph for the current index:
Create a PDF File With Text and an Image Create a PDF File With Text and an Image
---------------------------------------- ----------------------------------------
The `image2pdf.c` example code creates a PDF file containing a JPEG or PNG The `image2pdf.c` example code creates a PDF file containing a GIF, JPEG, or PNG
image file and optional caption on a single page. The `create_pdf_image_file` image file and optional caption on a single page. The `create_pdf_image_file`
function creates the PDF file, embeds a base font and the named JPEG or PNG function creates the PDF file, embeds a base font and the named JPEG or PNG
image file, and then creates a page with the image centered on the page with any image file, and then creates a page with the image centered on the page with any

14
examples/pdfioinfo.c
View File

@@ -1,7 +1,7 @@
// //
// PDF metadata example for PDFio. // PDF metadata example for PDFio.
// //
// Copyright © 2023-2025 by Michael R Sweet. // Copyright © 2023-2026 by Michael R Sweet.
// //
// Licensed under Apache License v2.0. See the file "LICENSE" for more // Licensed under Apache License v2.0. See the file "LICENSE" for more
// information. // information.
@@ -113,16 +113,10 @@ main(int argc, // I - Number of command-line arguments
for (cur = 0, prev = 0; cur < num_pages; cur ++) for (cur = 0, prev = 0; cur < num_pages; cur ++)
{ {
// Find the MediaBox for this page in the page tree... // Find the MediaBox for this page in the page tree...
for (page = pdfioFileGetPage(pdf, cur); page = pdfioFileGetPage(pdf, cur);
page != NULL;
page = pdfioDictGetObj(page_dict, "Parent"))
{
cur_box.x1 = cur_box.x2 = cur_box.y1 = cur_box.y2 = 0.0;
page_dict = pdfioObjGetDict(page);
if (pdfioDictGetRect(page_dict, "MediaBox", &cur_box)) cur_box.x1 = cur_box.x2 = cur_box.y1 = cur_box.y2 = 0.0;
break; pdfioPageGetRect(page, "MediaBox", &cur_box);
}
// If this MediaBox is different from the previous one, show the range of // If this MediaBox is different from the previous one, show the range of
// pages that have that size... // pages that have that size...

11
pdfio-content.c
View File

@@ -2141,13 +2141,14 @@ pdfioFileCreateImageObjFromData(
// //
// 'pdfioFileCreateImageObjFromFile()' - Add an image object to a PDF file from a file. // 'pdfioFileCreateImageObjFromFile()' - Add an image object to a PDF file from a file.
// //
// This function creates an image object in a PDF file from a JPEG or PNG file. // This function creates an image object in a PDF file from a GIF, JPEG, or PNG
// The "filename" parameter specifies the name of the JPEG or PNG file, while // file. The "filename" parameter specifies the name of the GIF, JPEG, or PNG
// the "interpolate" parameter specifies whether to interpolate when scaling the // file, while the "interpolate" parameter specifies whether to interpolate when
// image on the page. // scaling the image on the page.
// //
// > Note: PNG files containing transparency cannot be used when producing // > Note: PNG files containing transparency cannot be used when producing
// > PDF/A files. // > PDF/A files. Files containing animation yield the final frame of the
// > animation.
// //
pdfio_obj_t * // O - Object pdfio_obj_t * // O - Object