README file for Base ClibPDF [1999-12-12 version 2.02-r1-1] This package is released under: FastIO ClibPDF Software License Version 1.20, September 14, 1999. ClibPDF and Premium ClibPDF are not public-domain or free software. ===================================================================================== New Features and Recent History ===================================================================================== 1999-12-12 [io] (version 2.02-r1-1) -- Malloc size bug in cpdfInit.c was discovered by James Walker. It has been fixed and this fix should eliminate excessive memory use for TIFF2PDF and similar applications with thousands of pages of images per PDF file. Most applications would not have hit this bug. The excessive memory allocation was imageIdx storage in CPDFpageInfo. 1999-12-09 [io] (version 2.02-r1-0) 1999-12-04 [io] (version 2.01-r2-13) -- Compiler warnings and errors under MacOS9 and Sun CC cleaned up. (Thanks to J.W. Walker, and Pierre-Yves Monnet.) -- Use of thread-safe localtime_r() where available. cpdf_localtime() now takes an extra argument for "struct tm" buffer. (See #define THREAD_SAFE_TIME_FUNCS in cpdfUtil.c) -- Unicode binary strings are now escaped internally for '\', '(', and ')'. More Notes on Unicode for bookmarks and annotations. Unicode text is now automatically escaped for PDF string secial characters: '(', ')', and '\' (See page 348 of PDF Reference Manual v1.3). It also additionally converts CR char (0x0d) into "\r". Newlines in annotations do not work otherwise in Acrobat (Reader). I am not sure if this is documented, but that is the way it is. Also, text to be inserted into annotations must be prepared with the MacOS end-of-line (EOL) convention. That is, use CR (0x0d) alone to indicate newlines in annotation text. This applies to both Unicode and non-Unicode text. Unix convention LF (0x0a) does not produce newlines, and Windows/DOS convention CRLF (0x0d 0x0a) causes undesired indentation of the new line. [1999-11-27] Unicode support for outlines (bookmarks), annotations, and text in page content has been added. void cpdf_hexStringMode(CPDFdoc *pdf, int flag); This function sets a new mode for text strings to be either HEX or standard ASCII. This call should be used with argument YES before HEX-coded Unicode strings are used in annotation, outline and basic text functions such as cpdf_text(). cpdf_hexStringMode(pdf, YES); places text API functions to accept HEX-coded strings. cpdf_hexStringMode(pdf, NO); must be used to restore standard ASCII-mode for strings. Note that you cannot yet use Unicode text with cpdf_textAligned() or any TextBox functions. This is because the string width function, cpdf_stringWidth() used internally to align text, does not work yet for Unicode. Please limit the use of Unicode for page test drawing to the following functions or their "raw" versions. cpdf_text(), cpdf_textShow(), and cpdf_textCRLFshow(). char *cpdf_convertBinaryToHex(const unsigned char *datain, char *hexout, long length, int addFEFF); /* datain - binary data of size "length" hexout - Converted HEX string is placed into this output buffer. Buffer for "hexout" must be allocated by the caller with a storage for a string of size at least 2*length+5 (considering possible addition of "FEFF" and string terminator). length - byte length of input binary data pointed to by datain. addFEFF - If non-zero, the function will check if "datain" begins with "FEFF" (in binary) and if not, prepend it to the output HEX representation. If it is zero, nothing is prepended. */ unsigned char *cpdf_convertHexToBinary(const char *hexin, unsigned char *binout, long *length); /* hexin - HEX string input (non-HEX characters are simply skipped, i.e., CR LF may be present). binout - Converted binary data is placed into this output buffer. The buffer for binout must be allocated by the caller, and must have the size of sizeof(hexin)/2 + 1 at a minimum. length - This variable will contain the byte length of converted binary data in "binout." */ ===================================================================================== Premium ClibPDF ONLY (Similar functionality is available in base ClibPDF as cpdf_placeInLineImage().) README for pcpdfRawImg.c: cpdf_placeImageData(); cpdf_rawPlaceImageData(); [1999-11-20] int cpdf_placeImageData(CPDFdoc *pdf, const char *uniqueID, const void *imagedata, long length, int nx, int ny, int ncomp_per_pixel, int bits_per_sample, float x, float y, float angle, float width, float height, int flags, CPDFimgAttr *imattr); int cpdf_rawPlaceImageData(CPDFdoc *pdf, const char *uniqueID, const void *imagedata, long length, int nx, int ny, int ncomp_per_pixel, int bits_per_sample, float x, float y, float angle, float width, float height, int flags, CPDFimgAttr *imattr); These two functions place bitmap image data that reside in memory (computed or preloaded from a file and decompressed) into a PDF via image XObject. They work in a similar way to cpdf_placeInLineImage(), but the difference is that the image data can be large and shared across multiple uses within a PDF file. In-line images are not shared across multiple instances. const char *uniqueID -- Give a unique string identifying image data uniquely within a PDF file. This is used for keeping only one copy of image data for a PDF file. const void *imagedata -- This is your image data in uncompressed form. You must pass the image data as expected by PDF. If PDF requires byte alignment at the end of a scan line (I don't know), you must take care of it. Also, any byte or bit-order issues must be taken care of by you, the programmer. The function doesn't do anything in these areas. It simply compresses the data (by Flate if compression is ON), and inserts it into PDF. long length ---------- Number of bytes in imagedata. int nx, ny ----------- Number of pixels in X and Y dimensions, respectively. int ncomp_per_pixel -- Number of color components (e.g, RGB image should have 3 for this, For CMYK, it should be 4). int bits_per_sample -- Number of bits per component (sample). For 8-bit gray image, this should be 8. For 24-bit RGB image (8 bit for each of RGB), this should be 8. float x, y ----------- Position of the lower-left corner of the image. float width, height -- Size of the image in points (1/72 inches). NOTE: this is true for BOTH functions above. int flags ------------ Bit-0: IM_GSAVE - (LSB) is "gsave" flag. Usually only this is needed. Bit-1: IM_IMAGEMASK - if 1 and B/W images (1-bit per pixel), the image data is used as /ImageMask. This should not be used with grayscale or color images. Bit-2: IM_INVERT - if 1, gray or B/W sense is inverted (negative image). Bit-3 and up: Reserved Use above defines by OR'ing them, as in IM_GSAVE | IM_INVERT. CPDFimgAttr *imattr -- Always pass NULL for now. ----------- int cpdf_importImage(CPDFdoc *pdf, const char *imagefile, int type, float x, float y, float angle, float *width, float *height, float *xscale, float *yscale, int flags); NOTE: the last argument of cpdf_importImage() and its "raw" version has been renamed to "flags" and its bit values are interpreted in the same way as described for cpdf_placeImageData(). All bits should work as described, except that all flags other than IM_GSAVE will be ignored for PDFIMG (CPDF_IMG type). ==================================================================== Porting the source code with the old API (v1.x) ==================================================================== [1] cpf_open(int mode) -> cpdf_open(int, CPDFdocLimits *dL) If the default document limits are OK, typical usage is now: CPDFdoc *pdf; pdf = cpdf_open(0, NULL); [2] cpdf_setDocumentLimits() is now obsolete, and has been merged with cpdf_open() as above. Do instead: CPDFdocLimits dL = {120, -1, -1, -1, 8000}; /* -1 keeps default */ pdf = cpdf_open(0, &dL); or Set values to individual members of CPDFdocLimits struct: dL.nMaxPages = 120; dL.nMaxFonts = -1; dL.nMaxImages = -1; dL.nMaxAnnots = -1; dL.nMaxObjects = 8000; [3] cpdf_setViewerPreferences() now takes a pointer to a CPDFviewerPrefs struct as in: CPDFviewerPrefs vP = {PM_OUTLINES, 0, 0, 0, 0, 0, 0, 0}; cpdf_setViewerPreferences(pdf, &vP); The above will have the book mark view open upon PDF file opening. [4] Many (but not all) functions now take a pointer to document context struct as the first argument. This pointer is returned by cpdf_open(). Examples of change: cpdf_open(0); -> pdf = cpdf_open(0, NULL); cpdf_moveto(x, y); -> cpdf_moveto(pdf, x, y); cpdf_fill(); -> cpdf_fill(pdf); cpdf_pageInit(1, PORTRAIT, A4, A4); -> cpdf_pageInit(pdf, 1, PORTRAIT, A4, A4); The list of all functions that needs this modification can be obtained by this command: grep "CPDFdoc \*pdf" cpdflib.h [5] cpdf_textBox(), and cpdf_rawTextBox() now requires an additional argument, orientation angle, after (xl, yl, width, height). See the API manual and cpdflib.h. [6] New member has been added to CPDFtboxAttr struct (see cpdflib.h and the manual) for use with cpdf_textBox() and cpdf_textBoxFit(), and their raw versions. Do not forget to add: tboxAttr.noMark = 0; if you don't use NULL, and you use a struct to modifiy the default attributes of text boxes. [7] Endian.h is no longer needed or created during the make process. [8] Private functions have been moved to cpdf_private.h. [9] Test program: testpdf.c now creates 2 slightly different PDF files in a interleaved way at the same time. This is not an ideal test of multi-threading and thread safety. Please band on the new ClibPDF with respect to thread safety, and let us know of any problems. [10] For multi-threaded application developer, please review the first half of file cpdfUtil.c, and evaluate the need for mutex locks there. [11] ### IMPORTANT ###: Use multi-threaded C run time library for multi-threaded applications. I believe there is LIBCMT.lib for Microsoft VC++ which is supposed to be thread-safe. Use this instead of standard LIBC. [12] Reverse the order of cpdf_close(pdf); cpdf_launchPreview(pdf); in all examples and programs that automatically open the document in Acrobat Reader or other PDF viewers. It must be: cpdf_launchPreview(pdf); cpdf_close(pdf);. "pdf" is freed by cpdf_close(), so it can't be used after that. Sam info@fastio.com ======================================================================== Same content as ClibPDF version 1.02 below ======================================================================== ## What is ClibPDF ClibPDF is a library of ANSI C functions, distributed in source form, for creating PDF (Acrobat) files directly via C language programs without relying on any Adobe Acrobat tools and related products. It is suitable for fast dynamic PDF Web page generation in response to user input and server-side data, and also for implementing publication-quality graph plotting for both on-screen viewing and printing in any custom application. Since there is minimal platform-specific code, it is ideal as cross-platform graphing solutions with minimal developement efforts. Generated PDF files are viewed and printed by auto-launching Adobe Acrobat Reader or any other PDF viewer available free for many platforms. Note that ClibPDF is for PDF file creation only. It has no support for reading or editing existing PDF files. ## Notable Features of ClibPDF - FONTS: Support for Adobe 39 PS Type1 fonts, plus 2 custom fonts (Helvetica-like fixed-pitch font, Small-Cap font). Also, 7 Asian language (CJK) fonts with a total of 28 variations. - Multi-level Outline (Book Mark) support - hierarchical tree - Most basic PDF drawing primitives are supported, plus arc and circle. - Plot domains (linear, semi-log, log-log) with mesh to give graph paper appearance. - Axes (linear, log, date) with flexible tick marks, numbering, and labelling. - Markers, pointers, error bars for data points. - Multi-page documents may be generated in any page order, and pages may be written in an interleaved manner. - Support for Flate/Zlib compression for fast web download (No need for LZW license from Unisys.) - In-memory PDF generation (no temp files). - Transition, timed slide show support. ## Possible Applications - Fast, light-weight CGI for dynamic PDF web pages generation. - Report generation in medical, scientific, and industrial test equipment (and plots may be used directly in publications). - Giving legacy console-type applications an attractive graphic output via auto-launched Arobat Reader (or any PDF viewer). - Cross-platform graphing solutions. - A unified imaging model for X-Window applications for beautiful screen AND printed output (no more ugly screen dumps). This eases the pain of the death of DPS (Display PostScript). ## Copyright Notice Copyright (C)1998, 1999 FastIO Systems, All Rights Reserved. For conditions of use, license, and distribution, see LICENSE.txt or LICENSE.pdf. ClibPDF is NOT public domain software. ## License, Copying, and Distribution ClibPDF is free OR commercial depending on how and by whom it is used. ClibPDF is free for non-profit personal use, and use by educational, non-profit, and government organizations. Commercial license is required for use by for-profit entities (also refered to as commercial users), including commercial web-site deployment (including intranet), inclusion in in-house business, production, manufacturing and research applications, for-profit use by individuals, inclusion in commercial applications, libraries, and tools that are sold or bundled with other commercial products. There is a special deferment provision for shareware developers. An automatic free 30-day examination period is granted for commercial users for the purpose of evaluting ClibPDF. The summary of license terms described above is an overview and is not legally binding. Exact and legally accurate details of licensing terms are described in the file LICENSE.pdf included in the distribution or at /LICENSE.pdf. We welcome feedback regarding the feature list, licensing, bugs, and improvements and any other suggestions. Please send comments to info@fastio.com. ## Compile and Install [1] Install Adobe Acrobat Reader or a PDF viewer application. (Free from http://www.adobe.com/prodindex/acrobat/readstep.html) There is also a link to the download page for Asian languages fonts (free) on this page (see near bottom left). Acrobat Reader is needed only for viewing the PDF file on the development system. If you are using ClibPDF strictly for Web server applications (you view the PDFs on other client machines), there is no need to install either Acrobat or Asian fonts. [2] Compile and Install library Please see file README., if present, for further platform-specific details for Mac/PC platforms. For Unix variants: BSDI/Linux/FreeBSD/NEXTSTEP/OPENSTEP/MacOS X Server/SunOS/SGI cd source mv Makefile Makefile.orig For standard ClibPDF: cp Makefile. Makefile For Premium ClibPDF: cp Makefile.P Makefile make lib make install (/usr/local/lib and include must be writable) make test (creates testpdf executable) ./testpdf cd .. cd examples (compile and run examples) If Makefile. or Makefile.P does not exist for your platform of choice, use Makefile.* of the closest variant, and also edit config.h. Differences should really be minor. We can't generally help with specific compiler/linker problems for any given platform. ## Platforms tested so far: -- Unix variants -- BSDI BSD/OS 3.1 (gcc 2.7.2.1) FreeBSD 2.2.8-STABLE (gcc 2.7.2.1) Linux 2.0.34 (Red Hat 5.1) (gcc 2.7.2.3) MacOS X Server 1.1 NEXTSTEP 3.2, 3.3, OPENSTEP 4.2 SGI IRIX 6.2 (gcc-2.8.1) -- Thanks to Matt Warner SunOS 5.4 / (SUNWspro/SC4.0) Sun Solaris 7 (gcc-2.95.1) HP-UX B.11.00 AIX 4.2 -- Non-Unix -- MacOS 8.6 (Metrowerks CWPro4/IDE 3.2) -- See also: README.MacOS8 Windows 95/98/NT 4.0 SP3/SP4 (VC++ 6.0) -- See also: README.win32 Cygwin b20.1 (gcc egcs-2.91.57) -- Thanks to Stipe Tolj ## Relationships to other software ClibPDF incorporates a portion of ZLIB Flate compression library. (C) 1995-1998 Jean-loup Gailly and Mark Adler [See README-zlib] Jpegsize.c and its header files been taken from the Independent JPEG Group's software distribution. It is a modified version of rdjpgcom.c. An image file, testimg.jpg, has also been taken from the JPEG distribution. Copyright (C) 1994-1997, Thomas G. Lane. [See README-jpeg] Code from "Technote 1002: On Launching an App with a Document" from Apple Developer Technical Support (DTS) is used in cpdfPreview.c. The original code may be found at: http://developer.apple.com/technotes/tn/tn1002.html Copyright (C) 1995 by Apple Computer, Inc. All Rights Reserved. Files cpdfPFM.h and cpdfReadPFM.c contain public-domain code from the following: Title: pfm2afm - Convert Windows .pfm files to .afm files Author: Ken Borgendale 10/9/91 Version 1.0 Copyright: pfm2afm - Copyright (C) IBM Corp., 1991 This code is released for public use as long as the copyright remains intact. This code is provided asis without any warrenties, express or implied Four Utopia family of fonts that accompany this distribution have been donated to the public domain by Adobe Systems (see README.Utopia). These items listed above are the only pieces of code/software that originate from others. The rest of the code has been written entirely from scratch, and is Copyright (C) 1998, 1999 FastIO Systems. Conceptually, ClibPDF has been inspired by public-domaiin Cgraph for PostScript (http://totoro.berkeley.edu/software/A_Cgraph.html), but ClibPDF is much more powerful. Again, no code from Cgraph (PS) has been used. Cgraph plot markers have been reimplemented. NO part of ClibPDF is derived from or related to either of two C-language PDF libraries; Adobe PDF Library or Thomas Merz's PDFLib. ClibPDF has been written completely independently. I have seen some documentation for each, but no source code. Sam Ohzawa -- ClibPDF, JlibPDF, and FastIO are trademarks of FastIO Systems. Adobe, Acrobat, Exchange, and PostScript are tademarks of Adobe Systems Inc. All other products or name brands are trademarks of their respective holders.