dany/pdfio
1
0
Fork 0
mirror of https://github.com/michaelrsweet/pdfio.git synced 2024-12-26 13:28:22 +01:00
Code Issues Packages Projects Releases Wiki Activity

Doco updates.

Browse Source
This commit is contained in:
Michael R Sweet 2024-12-15 11:28:09 -05:00
parent 2c8a996875
commit d4e3bbcf16
No known key found for this signature in database
GPG Key ID: BE67C75EC81F3244
1 changed files with 52 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

72
doc/pdfio.md
View File

@ -465,7 +465,9 @@ You create a new PDF file using the [`pdfioFileCreate`](@@) function:
pdfio_rect_t media_box = { 0.0, 0.0, 612.0, 792.0 }; // US Letter 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 }; // w/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); pdfio_file_t *pdf = pdfioFileCreate("myoutputfile.pdf", "2.0",
&media_box, &crop_box,
error_cb, error_data);
``` ```
where the six arguments to the function are the filename ("myoutputfile.pdf"), where the six arguments to the function are the filename ("myoutputfile.pdf"),
@ -481,7 +483,9 @@ function:
pdfio_rect_t media_box = { 0.0, 0.0, 612.0, 792.0 }; // US Letter 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 }; // w/0.5" margins pdfio_rect_t crop_box = { 36.0, 36.0, 576.0, 756.0 }; // w/0.5" margins
pdfio_file_t *pdf = pdfioFileCreateOutput(output_cb, output_ctx, "2.0", &media_box, &crop_box, error_cb, error_data); pdfio_file_t *pdf = pdfioFileCreateOutput(output_cb, output_ctx, "2.0",
&media_box, &crop_box,
error_cb, error_data);
``` ```
Once the file is created, use the [`pdfioFileCreateObj`](@@), Once the file is created, use the [`pdfioFileCreateObj`](@@),
@ -638,13 +642,16 @@ spaces:
pdfio_file_t *pdf = pdfioFileCreate(...); pdfio_file_t *pdf = pdfioFileCreate(...);
// Create an AdobeRGB color array // Create an AdobeRGB color array
pdfio_array_t *adobe_rgb = pdfioArrayCreateColorFromStandard(pdf, 3, PDFIO_CS_ADOBE); pdfio_array_t *adobe_rgb =
pdfioArrayCreateColorFromStandard(pdf, 3, PDFIO_CS_ADOBE);
// Create an Display P3 color array // Create an Display P3 color array
pdfio_array_t *display_p3 = pdfioArrayCreateColorFromStandard(pdf, 3, PDFIO_CS_P3_D65); pdfio_array_t *display_p3 =
pdfioArrayCreateColorFromStandard(pdf, 3, PDFIO_CS_P3_D65);
// Create an sRGB color array // Create an sRGB color array
pdfio_array_t *srgb = pdfioArrayCreateColorFromStandard(pdf, 3, PDFIO_CS_SRGB); pdfio_array_t *srgb =
pdfioArrayCreateColorFromStandard(pdf, 3, PDFIO_CS_SRGB);
``` ```
@ -670,6 +677,7 @@ font object for one of the base PDF fonts:
- "Times-Roman" - "Times-Roman"
- "ZapfDingbats" - "ZapfDingbats"
Except for Symbol and ZapfDingbats (which use a custom 8-bit character set),
PDFio always uses the Windows CP1252 subset of Unicode for these fonts. PDFio always uses the Windows CP1252 subset of Unicode for these fonts.
The second function is [`pdfioFileCreateFontObjFromFile`](@@) which creates a The second function is [`pdfioFileCreateFontObjFromFile`](@@) which creates a
@ -677,7 +685,8 @@ font object from a TrueType/OpenType font file, for example:
```c ```c
pdfio_file_t *pdf = pdfioFileCreate(...); pdfio_file_t *pdf = pdfioFileCreate(...);
pdfio_obj_t *arial = pdfioFileCreateFontObjFromFile(pdf, "OpenSans-Regular.ttf", false); pdfio_obj_t *arial =
pdfioFileCreateFontObjFromFile(pdf, "OpenSans-Regular.ttf", false);
``` ```
will embed an OpenSans Regular TrueType font using the Windows CP1252 subset of will embed an OpenSans Regular TrueType font using the Windows CP1252 subset of
@ -686,12 +695,16 @@ instead, for example:
```c ```c
pdfio_file_t *pdf = pdfioFileCreate(...); pdfio_file_t *pdf = pdfioFileCreate(...);
pdfio_obj_t *arial = pdfioFileCreateFontObjFromFile(pdf, "NotoSansJP-Regular.otf", true); pdfio_obj_t *arial =
pdfioFileCreateFontObjFromFile(pdf, "NotoSansJP-Regular.otf", true);
``` ```
will embed the NotoSansJP Regular OpenType font with full support for Unicode. will embed the NotoSansJP Regular OpenType font with full support for Unicode.
> Note: Not all fonts support Unicode. > Note: Not all fonts support Unicode, and most do not contain a full
> complement of Unicode characters. `pdfioFileCreateFontObjFromFile` does not
> perform any character subsetting, so the entire font file is embedded in the
> PDF file.
### Image Object Functions ### Image Object Functions
@ -705,7 +718,11 @@ in memory, for example:
```c ```c
pdfio_file_t *pdf = pdfioFileCreate(...); pdfio_file_t *pdf = pdfioFileCreate(...);
unsigned char data[1024 * 1024 * 4]; // 1024x1024 RGBA image data unsigned char data[1024 * 1024 * 4]; // 1024x1024 RGBA image data
pdfio_obj_t *img = pdfioFileCreateImageObjFromData(pdf, data, /*width*/1024, /*height*/1024, /*num_colors*/3, /*color_data*/NULL, /*alpha*/true, /*interpolate*/false); pdfio_obj_t *img =
pdfioFileCreateImageObjFromData(pdf, data, /*width*/1024,
/*height*/1024, /*num_colors*/3,
/*color_data*/NULL, /*alpha*/true,
/*interpolate*/false);
``` ```
will create an object for a 1024x1024 RGBA image in memory, using the default will create an object for a 1024x1024 RGBA image in memory, using the default
@ -717,11 +734,19 @@ example:
pdfio_file_t *pdf = pdfioFileCreate(...); pdfio_file_t *pdf = pdfioFileCreate(...);
// Create an AdobeRGB color array // Create an AdobeRGB color array
pdfio_array_t *adobe_rgb = pdfioArrayCreateColorFromMatrix(pdf, 3, pdfioAdobeRGBGamma, pdfioAdobeRGBMatrix, pdfioAdobeRGBWhitePoint); pdfio_array_t *adobe_rgb =
pdfioArrayCreateColorFromMatrix(pdf, 3, pdfioAdobeRGBGamma,
pdfioAdobeRGBMatrix,
pdfioAdobeRGBWhitePoint);
// Create a 1024x1024 RGBA image using AdobeRGB // Create a 1024x1024 RGBA image using AdobeRGB
unsigned char data[1024 * 1024 * 4]; // 1024x1024 RGBA image data unsigned char data[1024 * 1024 * 4]; // 1024x1024 RGBA image data
pdfio_obj_t *img = pdfioFileCreateImageObjFromData(pdf, data, /*width*/1024, /*height*/1024, /*num_colors*/3, /*color_data*/adobe_rgb, /*alpha*/true, /*interpolate*/false); pdfio_obj_t *img =
pdfioFileCreateImageObjFromData(pdf, data, /*width*/1024,
/*height*/1024, /*num_colors*/3,
/*color_data*/adobe_rgb,
/*alpha*/true,
/*interpolate*/false);
``` ```
The "interpolate" argument specifies whether the colors in the image should be The "interpolate" argument specifies whether the colors in the image should be
@ -733,7 +758,9 @@ function to copy the image into a PDF image object, for example:
```c ```c
pdfio_file_t *pdf = pdfioFileCreate(...); pdfio_file_t *pdf = pdfioFileCreate(...);
pdfio_obj_t *img = pdfioFileCreateImageObjFromFile(pdf, "myphoto.jpg", /*interpolate*/true); pdfio_obj_t *img =
pdfioFileCreateImageObjFromFile(pdf, "myphoto.jpg",
/*interpolate*/true);
``` ```
@ -856,7 +883,9 @@ show_pdf_info(const char *filename)
// Open the PDF file with the default callbacks... // Open the PDF file with the default callbacks...
pdf = pdfioFileOpen(filename, /*password_cb*/NULL, /*password_cbdata*/NULL, /*error_cb*/NULL, /*error_cbdata*/NULL); pdf = pdfioFileOpen(filename, /*password_cb*/NULL,
/*password_cbdata*/NULL, /*error_cb*/NULL,
/*error_cbdata*/NULL);
if (pdf == NULL) if (pdf == NULL)
return; return;
@ -892,7 +921,8 @@ the page with the text centered below:
void void
create_pdf_image_file(const char *pdfname, const char *imagename, const char *caption) create_pdf_image_file(const char *pdfname, const char *imagename,
const char *caption)
{ {
pdfio_file_t *pdf; pdfio_file_t *pdf;
pdfio_obj_t *font; pdfio_obj_t *font;
@ -905,7 +935,9 @@ create_pdf_image_file(const char *pdfname, const char *imagename, const char *ca
// Create the PDF file... // Create the PDF file...
pdf = pdfioFileCreate(pdfname, /*version*/NULL, /*media_box*/NULL, /*crop_box*/NULL, /*error_cb*/NULL, /*error_cbdata*/NULL); pdf = pdfioFileCreate(pdfname, /*version*/NULL, /*media_box*/NULL,
/*crop_box*/NULL, /*error_cb*/NULL,
/*error_cbdata*/NULL);
// Create a Courier base font for the caption // Create a Courier base font for the caption
font = pdfioFileCreateFontObjFromBase(pdf, "Courier"); font = pdfioFileCreateFontObjFromBase(pdf, "Courier");
@ -925,9 +957,9 @@ create_pdf_image_file(const char *pdfname, const char *imagename, const char *ca
width = pdfioImageGetWidth(image); width = pdfioImageGetWidth(image);
height = pdfioImageGetHeight(image); height = pdfioImageGetHeight(image);
// Default media_box is "universal" 595.28x792 points (8.27x11in or 210x279mm) // Default media_box is "universal" 595.28x792 points (8.27x11in or
// Use margins of 36 points (0.5in or 12.7mm) with another 36 points for the // 210x279mm). Use margins of 36 points (0.5in or 12.7mm) with another
// caption underneath... // 36 points for the caption underneath...
swidth = 595.28 - 72.0; swidth = 595.28 - 72.0;
sheight = swidth * height / width; sheight = swidth * height / width;
if (sheight > (792.0 - 36.0 - 72.0)) if (sheight > (792.0 - 36.0 - 72.0))
@ -944,8 +976,8 @@ create_pdf_image_file(const char *pdfname, const char *imagename, const char *ca
// Draw the caption in black... // Draw the caption in black...
pdfioContentSetFillColorDeviceGray(page, 0.0); pdfioContentSetFillColorDeviceGray(page, 0.0);
// Compute the starting point for the text - Courier is monospaced with a // Compute the starting point for the text - Courier is monospaced
// nominal width of 0.6 times the text height... // with a nominal width of 0.6 times the text height...
tx = 0.5 * (595.28 - 18.0 * 0.6 * strlen(caption)); tx = 0.5 * (595.28 - 18.0 * 0.6 * strlen(caption));
// Position and draw the caption underneath... // Position and draw the caption underneath...