diff --git a/Makefile b/Makefile index 2c8c908..43f357a 100644 --- a/Makefile +++ b/Makefile @@ -36,7 +36,10 @@ prefix = /usr/local # Files -LIBOBJS = \ +PUBHEADERS = \ + pdfio.h \ + pdfio-content.h +PUBOBJS = \ pdfio-array.o \ pdfio-common.o \ pdfio-content.o \ @@ -47,7 +50,9 @@ LIBOBJS = \ pdfio-stream.o \ pdfio-string.o \ pdfio-token.o \ - pdfio-value.o \ + pdfio-value.o +LIBOBJS = \ + $(PUBOBJS) \ ttf.o OBJS = \ $(LIBOBJS) \ @@ -80,7 +85,7 @@ clean: # Install everything install: $(TARGETS) -mkdir -p $(DESTDIR)$(prefix)/include - cp pdfio.h pdfio-content.h $(DESTDIR)$(prefix)/include + cp $(PUBHEADERS) $(DESTDIR)$(prefix)/include -mkdir -p $(DESTDIR)$(prefix)/lib cp libpdfio.a $(DESTDIR)$(prefix)/lib $(RANLIB) $(DESTDIR)$(prefix)/lib/libpdfio.a @@ -145,7 +150,7 @@ DOCFLAGS = \ .PHONY: doc doc: - codedoc $(DOCFLAGS) --title "PDFio Programming Manual v$(VERSION)" pdfio.h $(LIBOBJS:.o=.c) --body doc/pdfio.md --coverimage doc/pdfio-512.png pdfio.xml >doc/pdfio.html + codedoc $(DOCFLAGS) --title "PDFio Programming Manual v$(VERSION)" $(PUBHEADERS) $(PUBOBJS:.o=.c) --body doc/pdfio.md --coverimage doc/pdfio-512.png pdfio.xml >doc/pdfio.html codedoc $(DOCFLAGS) --title "pdf read/write library" --man pdfio --section 3 --body doc/pdfio.md pdfio.xml >doc/pdfio.3 rm -f pdfio.xml diff --git a/doc/pdfio.3 b/doc/pdfio.3 index 28c5160..56c1e75 100644 --- a/doc/pdfio.3 +++ b/doc/pdfio.3 @@ -1,4 +1,4 @@ -.TH pdfio 3 "pdf read/write library" "2021-07-07" "pdf read/write library" +.TH pdfio 3 "pdf read/write library" "2021-07-18" "pdf read/write library" .SH NAME pdfio \- pdf read/write library .SH Introduction @@ -349,6 +349,68 @@ No filter PDFIO_FILTER_RUNLENGTH .br RunLengthDecode filter (reading only) +.SS pdfio_linecap_e +Line capping modes +.TP 5 +PDFIO_LINECAP_BUTT +.br +Butt ends +.TP 5 +PDFIO_LINECAP_ROUND +.br +Round ends +.TP 5 +PDFIO_LINECAP_SQUARE +.br +Square ends +.SS pdfio_linejoin_e +Line joining modes +.TP 5 +PDFIO_LINEJOIN_BEVEL +.br +Bevel joint +.TP 5 +PDFIO_LINEJOIN_MITER +.br +Miter joint +.TP 5 +PDFIO_LINEJOIN_ROUND +.br +Round joint +.SS pdfio_textrendering_e +Text rendering modes +.TP 5 +PDFIO_TEXTRENDERING_FILL +.br +Fill text +.TP 5 +PDFIO_TEXTRENDERING_FILL_AND_STROKE +.br +Fill then stroke text +.TP 5 +PDFIO_TEXTRENDERING_FILL_AND_STROKE_PATH +.br +Fill then stroke text and add to path +.TP 5 +PDFIO_TEXTRENDERING_FILL_PATH +.br +Fill text and add to path +.TP 5 +PDFIO_TEXTRENDERING_INVISIBLE +.br +Don't fill or stroke (invisible) +.TP 5 +PDFIO_TEXTRENDERING_STROKE +.br +Stroke text +.TP 5 +PDFIO_TEXTRENDERING_STROKE_PATH +.br +Stroke text and add to path +.TP 5 +PDFIO_TEXTRENDERING_TEXT_PATH +.br +Add text to path (invisible) .SS pdfio_valtype_e PDF value types .TP 5 @@ -1505,8 +1567,37 @@ pdfio_obj_t * pdfioFileCreateICCObjFromFile ( size_t num_colors ); .fi +.SS pdfioFileCreateImageObjFromData +Add image object(s) to a PDF file from memory. +.PP +.nf +pdfio_obj_t * pdfioFileCreateImageObjFromData ( + pdfio_file_t *pdf, + const unsigned char *data, + size_t width, + size_t height, + size_t num_colors, + pdfio_array_t *color_data, + bool alpha, + bool interpolate +); +.fi +.PP +This function creates image object(s) in a PDF file from a data buffer in +memory. The "data" parameter points to the image data as 8-bit color values. +The "width" and "height" parameters specify the image dimensions. The +"num_colors" parameter specifies the number of color components (\fB1\fR for +grayscale, \fB3\fR for RGB, and \fB4\fR for CMYK) and the "alpha" parameter specifies +whether each color tuple is followed by an alpha value. The "color_data" +parameter specifies an optional color space array for the image - if \fBNULL\fR, +the image is encoded in the corresponding device color space. The +"interpolate" parameter specifies whether to interpolate when scaling the +image on the page. +.PP +Note: When creating an image object with alpha, a second image object is +created to hold the "soft mask" data for the primary image. .SS pdfioFileCreateImageObjFromFile -Add an image object to a PDF file. +Add an image object to a PDF file from a file. .PP .nf pdfio_obj_t * pdfioFileCreateImageObjFromFile ( @@ -1517,6 +1608,9 @@ pdfio_obj_t * pdfioFileCreateImageObjFromFile ( .fi .PP This function creates an image object in a PDF file from a JPEG or PNG file. +The "filename" parameter specifies the name of the JPEG or PNG file, while +the "interpolate" parameter specifies whether to interpolate when scaling the +image on the page. .PP .IP 5 Note: Currently PNG support is limited to grayscale, RGB, or indexed files @@ -2020,194 +2114,6 @@ This function creates a formatted string associated with the PDF file .PP \fBNULL\fR is returned on error, otherwise a \fBchar *\fR that is valid until \fBpdfioFileClose\fR is called. -.SS ttfCreate -Create a new font object for the named font family. -.PP -.nf -ttf_t * ttfCreate ( - const char *filename, - size_t idx, - ttf_err_cb_t err_cb, - void *err_data -); -.fi -.SS ttfDelete -Free all memory used for a font family object. -.PP -.nf -void ttfDelete ( - ttf_t *font -); -.fi -.SS ttfGetAscent -Get the maximum height of non-accented characters. -.PP -.nf -int ttfGetAscent ( - ttf_t *font -); -.fi -.SS ttfGetBounds -Get the bounds of all characters in a font. -.PP -.nf -ttf_rect_t * ttfGetBounds ( - ttf_t *font, - ttf_rect_t *bounds -); -.fi -.SS ttfGetCMap -Get the Unicode to glyph mapping table. -.PP -.nf -const int * ttfGetCMap ( - ttf_t *font, - size_t *num_cmap -); -.fi -.SS ttfGetCapHeight -Get the height of capital letters. -.PP -.nf -int ttfGetCapHeight ( - ttf_t *font -); -.fi -.SS ttfGetCopyright -Get the copyright text for a font. -.PP -.nf -const char * ttfGetCopyright ( - ttf_t *font -); -.fi -.SS ttfGetDescent -Get the maximum depth of non-accented characters. -.PP -.nf -int ttfGetDescent ( - ttf_t *font -); -.fi -.SS ttfGetExtents -Get the extents of a UTF-8 string. -.PP -.nf -ttf_rect_t * ttfGetExtents ( - ttf_t *font, - float size, - const char *s, - ttf_rect_t *extents -); -.fi -.PP -This function computes the extents of a UTF-8 string when rendered using the -specified font and size. -.SS ttfGetFamily -Get the family name of a font. -.PP -.nf -const char * ttfGetFamily ( - ttf_t *font -); -.fi -.SS ttfGetItalicAngle -Get the italic angle. -.PP -.nf -float ttfGetItalicAngle ( - ttf_t *font -); -.fi -.SS ttfGetMaxChar -Get the last character in the font. -.PP -.nf -int ttfGetMaxChar ( - ttf_t *font -); -.fi -.SS ttfGetMinChar -Get the first character in the font. -.PP -.nf -int ttfGetMinChar ( - ttf_t *font -); -.fi -.SS ttfGetNumFonts -Get the number of fonts in this collection. -.PP -.nf -size_t ttfGetNumFonts ( - ttf_t *font -); -.fi -.SS ttfGetPostScriptName -Get the PostScript name of a font. -.PP -.nf -const char * ttfGetPostScriptName ( - ttf_t *font -); -.fi -.SS ttfGetStretch -Get the font "stretch" value... -.PP -.nf -ttf_stretch_t ttfGetStretch ( - ttf_t *font -); -.fi -.SS ttfGetStyle -Get the font style. -.PP -.nf -ttf_style_t ttfGetStyle ( - ttf_t *font -); -.fi -.SS ttfGetVersion -Get the version number of a font. -.PP -.nf -const char * ttfGetVersion ( - ttf_t *font -); -.fi -.SS ttfGetWeight -Get the weight of a font. -.PP -.nf -ttf_weight_t ttfGetWeight ( - ttf_t *font -); -.fi -.SS ttfGetWidth -Get the width of a single character. -.PP -.nf -int ttfGetWidth ( - ttf_t *font, - int ch -); -.fi -.SS ttfGetXHeight -Get the height of lowercase letters. -.PP -.nf -int ttfGetXHeight ( - ttf_t *font -); -.fi -.SS ttfIsFixedPitch -Determine whether a font is fixedpitch. -.PP -.nf -bool ttfIsFixedPitch ( - ttf_t *font -); -.fi .SH STRUCTURES .SS pdfio_rect_s PDF rectangle @@ -2252,6 +2158,24 @@ Compression/decompression filters for streams .nf typedef enum pdfio_filter_e pdfio_filter_t; .fi +.SS pdfio_linecap_t +Line capping modes +.PP +.nf +typedef enum pdfio_linecap_e pdfio_linecap_t; +.fi +.SS pdfio_linejoin_t +Line joining modes +.PP +.nf +typedef enum pdfio_linejoin_e pdfio_linejoin_t; +.fi +.SS pdfio_matrix_t[3][2] +Transform matrix +.PP +.nf +typedef double pdfio_matrix_t[3][2]; +.fi .SS pdfio_obj_t Numbered object in PDF file .PP @@ -2270,17 +2194,24 @@ Object data stream in PDF file .nf typedef struct _pdfio_stream_s pdfio_stream_t; .fi +.SS pdfio_textrendering_t +Text rendering modes +.PP +.nf +typedef enum pdfio_textrendering_e pdfio_textrendering_t; +.fi .SS pdfio_valtype_t PDF value types .PP .nf typedef enum pdfio_valtype_e pdfio_valtype_t; .fi -.SS ssize_t -POSIX type not present on Windows... +.SH VARIABLES +.SS PDFIO_PUBLIC +C++ magic... .PP .nf -typedef __int64 ssize_t; +pdfio_dict_t *dict const char *name pdfio_obj_t *obj)PDFIO_PUBLIC; .fi .SH AUTHOR .PP diff --git a/doc/pdfio.html b/doc/pdfio.html index 8bd64a3..e3da18a 100644 --- a/doc/pdfio.html +++ b/doc/pdfio.html @@ -377,6 +377,7 @@ span.string {
Set the line ends style.
-bool pdfioContentSetLineCap(pdfio_stream_t *st, pdfio_linecap_t lc);
+bool pdfioContentSetLineCap(pdfio_stream_t *st, pdfio_linecap_t lc);st | @@ -1418,7 +1406,7 @@ bool pdfioContentSetLineCap(pdfio_stream_t *st, pd
---|
st | @@ -1603,7 +1591,7 @@ bool pdfioContentSetTextMatrix(pdfio_stream_t *st,
---|
st | @@ -2273,8 +2261,47 @@ characters such as the Euro symbol) subset of Unicode.
---|
Object
+Add image object(s) to a PDF file from memory.
++pdfio_obj_t *pdfioFileCreateImageObjFromData(pdfio_file_t *pdf, const unsigned char *data, size_t width, size_t height, size_t num_colors, pdfio_array_t *color_data, bool alpha, bool interpolate);
+PDF file | |
data | +Pointer to image data |
width | +Width of image |
height | +Height of image |
num_colors | +Number of colors |
color_data | +Colorspace data or NULL for default |
alpha | +true if data contains an alpha channel |
interpolate | +Interpolate image data? |
Object
+This function creates image object(s) in a PDF file from a data buffer in
+memory. The "data" parameter points to the image data as 8-bit color values.
+The "width" and "height" parameters specify the image dimensions. The
+"num_colors" parameter specifies the number of color components (1
for
+grayscale, 3
for RGB, and 4
for CMYK) and the "alpha" parameter specifies
+whether each color tuple is followed by an alpha value. The "color_data"
+parameter specifies an optional color space array for the image - if NULL
,
+the image is encoded in the corresponding device color space. The
+"interpolate" parameter specifies whether to interpolate when scaling the
+image on the page.
+
+Note: When creating an image object with alpha, a second image object is
+created to hold the "soft mask" data for the primary image.
Add an image object to a PDF file.
+Add an image object to a PDF file from a file.
pdfio_obj_t *pdfioFileCreateImageObjFromFile(pdfio_file_t *pdf, const char *filename, bool interpolate);
Object
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 JPEG or PNG file.
+The "filename" parameter specifies the name of the JPEG or PNG file, while
+the "interpolate" parameter specifies whether to interpolate when scaling the
+image on the page.
Note: Currently PNG support is limited to grayscale, RGB, or indexed files @@ -2849,7 +2879,7 @@ bool pdfioStreamGetToken(pdfio_stream_t *st, charpdfioStreamPeek
Peek at data in a stream.
-ssize_t pdfioStreamPeek(pdfio_stream_t *st, void *buffer, size_t bytes);
+ssize_t pdfioStreamPeek(pdfio_stream_t *st, void *buffer, size_t bytes);Parameters
+
st @@ -2905,7 +2935,7 @@ bool pdfioStreamPuts(pdfio_stream_t *st, const chapdfioStreamRead
Read data from a stream.
-ssize_t pdfioStreamRead(pdfio_stream_t *st, void *buffer, size_t bytes);
+ssize_t pdfioStreamRead(pdfio_stream_t *st, void *buffer, size_t bytes);Parameters
+
st @@ -2977,267 +3007,6 @@ char *pdfioStringCreatef(pdfio_file_t *pdf, const ch
NULL
is returned on error, otherwise achar *
that is valid untilpdfioFileClose
is called. -ttfCreate
-Create a new font object for the named font family.
--ttf_t *ttfCreate(const char *filename, size_t idx, ttf_err_cb_t err_cb, void *err_data);
-Parameters
--
-- filename -Filename - idx -Font number to create in collection (0-based) - err_cb -Error callback or NULL
to log to stderr- err_data -Error callback data Return Value
-New font object
-ttfDelete
-Free all memory used for a font family object.
--void ttfDelete(ttf_t *font);
-Parameters
--
-- font -Font ttfGetAscent
-Get the maximum height of non-accented characters.
--int ttfGetAscent(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Ascent in 1000ths
-ttfGetBounds
-Get the bounds of all characters in a font.
--ttf_rect_t *ttfGetBounds(ttf_t *font, ttf_rect_t *bounds);
-Parameters
--
-- font -Font - bounds -Bounds buffer Return Value
-Bounds or
-NULL
on errorttfGetCMap
-Get the Unicode to glyph mapping table.
--const int *ttfGetCMap(ttf_t *font, size_t *num_cmap);
-Parameters
--
-- font -Font - num_cmap -Number of entries in table Return Value
-CMap table
-ttfGetCapHeight
-Get the height of capital letters.
--int ttfGetCapHeight(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Capital letter height in 1000ths
-ttfGetCopyright
-Get the copyright text for a font.
--const char *ttfGetCopyright(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Copyright text
-ttfGetDescent
-Get the maximum depth of non-accented characters.
--int ttfGetDescent(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Descent in 1000ths
-ttfGetExtents
-Get the extents of a UTF-8 string.
--ttf_rect_t *ttfGetExtents(ttf_t *font, float size, const char *s, ttf_rect_t *extents);
-Parameters
--
-- font -Font - size -Font size - s -String - extents -Extents of the string Return Value
-Pointer to extents or
-NULL
on errorDiscussion
-This function computes the extents of a UTF-8 string when rendered using the -specified font and size.
-ttfGetFamily
-Get the family name of a font.
--const char *ttfGetFamily(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Family name
-ttfGetItalicAngle
-Get the italic angle.
--float ttfGetItalicAngle(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Angle in degrees
-ttfGetMaxChar
-Get the last character in the font.
--int ttfGetMaxChar(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Last character in font
-ttfGetMinChar
-Get the first character in the font.
--int ttfGetMinChar(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-First character in font
-ttfGetNumFonts
-Get the number of fonts in this collection.
--size_t ttfGetNumFonts(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Number of fonts
-ttfGetPostScriptName
-Get the PostScript name of a font.
--const char *ttfGetPostScriptName(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-PostScript name
-ttfGetStretch
-Get the font "stretch" value...
--ttf_stretch_t ttfGetStretch(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Stretch value
-ttfGetStyle
-Get the font style.
--ttf_style_t ttfGetStyle(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Style
-ttfGetVersion
-Get the version number of a font.
--const char *ttfGetVersion(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Version number
-ttfGetWeight
-Get the weight of a font.
--ttf_weight_t ttfGetWeight(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Weight
-ttfGetWidth
-Get the width of a single character.
--int ttfGetWidth(ttf_t *font, int ch);
-Parameters
--
-- font -Font - ch -Unicode character Return Value
-Width in 1000ths
-ttfGetXHeight
-Get the height of lowercase letters.
--int ttfGetXHeight(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-Lowercase letter height in 1000ths
-ttfIsFixedPitch
-Determine whether a font is fixedpitch.
--bool ttfIsFixedPitch(ttf_t *font);
-Parameters
--
-- font -Font Return Value
-
true
if fixed pitch,false
otherwiseData Types
pdfio_array_t
Array of PDF values
@@ -3264,6 +3033,21 @@ typedef struct _pdfio_file_s pdfio_file_t;typedef enum pdfio_filter_e pdfio_filter_t;
+pdfio_linecap_t
+Line capping modes
++typedef enum pdfio_linecap_e pdfio_linecap_t; +
+pdfio_linejoin_t
+Line joining modes
++typedef enum pdfio_linejoin_e pdfio_linejoin_t; +
+pdfio_matrix_t[3][2]
+Transform matrix
++typedef double pdfio_matrix_t[3][2]; +
pdfio_obj_t
Numbered object in PDF file
@@ -3279,16 +3063,16 @@ typedef struct pdfio_rect_s pdfio_rect_t;
typedef struct _pdfio_stream_s pdfio_stream_t;
+pdfio_textrendering_t
+Text rendering modes
++typedef enum pdfio_textrendering_e pdfio_textrendering_t; +
pdfio_valtype_t
PDF value types
typedef enum pdfio_valtype_e pdfio_valtype_t;
-ssize_t
-POSIX type not present on Windows...
--typedef __int64 ssize_t; -
Structures
pdfio_rect_s
PDF rectangle
@@ -3309,6 +3093,10 @@ typedef __int64 ssize_t;y2 Upper-right Y coordinate Variables
+PDFIO_PUBLIC
+C++ magic...
+pdfio_dict_t *dict const char *name pdfio_obj_t *obj) PDFIO_PUBLIC;
Constants
pdfio_filter_e
Compression/decompression filters for streams
@@ -3326,6 +3114,35 @@ typedef __int64 ssize_t;PDFIO_FILTER_NONE No filter PDFIO_FILTER_RUNLENGTH RunLengthDecode filter (reading only) pdfio_linecap_e
+Line capping modes
+Constants
++
++ PDFIO_LINECAP_BUTT Butt ends + PDFIO_LINECAP_ROUND Round ends + PDFIO_LINECAP_SQUARE Square ends pdfio_linejoin_e
+Line joining modes
+Constants
++
++ PDFIO_LINEJOIN_BEVEL Bevel joint + PDFIO_LINEJOIN_MITER Miter joint + PDFIO_LINEJOIN_ROUND Round joint pdfio_textrendering_e
+Text rendering modes
+Constants
++
+ PDFIO_TEXTRENDERING_FILL Fill text + PDFIO_TEXTRENDERING_FILL_AND_STROKE Fill then stroke text + PDFIO_TEXTRENDERING_FILL_AND_STROKE_PATH Fill then stroke text and add to path + PDFIO_TEXTRENDERING_FILL_PATH Fill text and add to path + PDFIO_TEXTRENDERING_INVISIBLE Don't fill or stroke (invisible) + PDFIO_TEXTRENDERING_STROKE Stroke text + PDFIO_TEXTRENDERING_STROKE_PATH Stroke text and add to path + PDFIO_TEXTRENDERING_TEXT_PATH Add text to path (invisible) pdfio_valtype_e
PDF value types
Constants
diff --git a/pdfio-content.c b/pdfio-content.c index 22095b5..f3dc1b8 100644 --- a/pdfio-content.c +++ b/pdfio-content.c @@ -1618,21 +1618,21 @@ pdfioFileCreateICCObjFromFile( // -// 'pdfioFileCreateImageObjFromData()' - Add an image object to a PDF file from memory. +// 'pdfioFileCreateImageObjFromData()' - Add image object(s) to a PDF file from memory. // -// This function creates an image object in a PDF file from a data buffer in -// memory. The "data" parameter points to the image data as 8-bit values. The -// "width" and "height" parameters specify the image dimensions. The -// "num_colors" parameter specifies the number of color components as follows: +// This function creates image object(s) in a PDF file from a data buffer in +// memory. The "data" parameter points to the image data as 8-bit color values. +// The "width" and "height" parameters specify the image dimensions. The +// "num_colors" parameter specifies the number of color components (`1` for +// grayscale, `3` for RGB, and `4` for CMYK) and the "alpha" parameter specifies +// whether each color tuple is followed by an alpha value. The "color_data" +// parameter specifies an optional color space array for the image - if `NULL`, +// the image is encoded in the corresponding device color space. The +// "interpolate" parameter specifies whether to interpolate when scaling the +// image on the page. // -// - 1 = grayscale -// - 2 = grayscale + alpha -// - 3 = RGB -// - 4 = RGBA -// -// The "color_data" parameter specifies an optional color space array for the -// image. The "interpolate" parameter specifies whether to interpolate when -// scaling the image on the page. +// Note: When creating an image object with alpha, a second image object is +// created to hold the "soft mask" data for the primary image. // pdfio_obj_t * // O - Object diff --git a/pdfio.h b/pdfio.h index 43a4be0..b973b96 100644 --- a/pdfio.h +++ b/pdfio.h @@ -48,7 +48,7 @@ extern "C" { // # ifdef _WIN32 -typedef __int64 ssize_t; // POSIX type not present on Windows... +typedef __int64 ssize_t; // POSIX type not present on Windows... @private@ # endif // _WIN32 typedef struct _pdfio_array_s pdfio_array_t;