diff --git a/Makefile b/Makefile index 43f357a..4f4bf9b 100644 --- a/Makefile +++ b/Makefile @@ -25,7 +25,7 @@ DSONAME = LDFLAGS = LIBS = -lm -lz RANLIB = ranlib -VERSION = 0.2 +VERSION = 1.0b1 prefix = /usr/local diff --git a/doc/pdfio.3 b/doc/pdfio.3 index 3328d40..f0f14cd 100644 --- a/doc/pdfio.3 +++ b/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 .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 @@ -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 diff --git a/doc/pdfio.html b/doc/pdfio.html index 465cc13..0190704 100644 --- a/doc/pdfio.html +++ b/doc/pdfio.html @@ -1,13 +1,13 @@ -PDFio Programming Manual v0.2 +PDFio Programming Manual v1.0b1 - +