PDFlib-0.6

N~tmPDF_circle()PDF_set_font()PDF_arc()PDF_show()PDF_lineto()PDF_open_TIFF()PDF_arc()PDFPDFlibReferenceManualThomasMerzAPIReferenceforPDFlib0.6,aClibraryfordynamicallygeneratingPDFfilesiiContentsContents1Introduction52PDFlibProgramming72.1AProgrammingClassicinC72.2ScriptingwithPerl,Tcl,andPython82.3GeneralProgrammingIssues102.4CoordinateSystemandVectorGraphics112.4.1TheCoordinateSystem112.4.2TheGraphicsStates112.5TextOutputandFonts132.5.1FontEmbeddingandAFMFiles132.5.2CharacterSetsandEncoding132.6RasterImages142.7ColorSpaces152.7.1ColorSpacesforTextandGraphics152.7.2ColorSpacesforRasterImages152.8BinaryOutputandCompression152.8.1BinaryandASCIIOutput152.8.2Compression153PDFlibAPIReference163.1DataStructures163.2GeneralFunctions163.3ErrorHandling173.4TextFunctions183.5GraphicsFunctions193.5.1GraphicsStateandCoordinateSystem193.5.2BasicDrawing203.5.3UsingthePath213.6ColorFunctions213.7ImageFunctions223.8HypertextFunctions233.9ConvenienceStuff243.10OptimizationTechniques243.11GeneralRestrictions24Contentsiii4SuppliedLibraryClients255EnvironmentBindings275.1CandC++LanguageBindings275.2Perl,Tcl,andPythonBindings275.3CommonGatewayInterface(CGI)285.4FunctionalProgramming285.5FutureBindings296ThePDFlibLicense307References318RevisionHistory32Index35Chapter1:Introduction51IntroductionWhatisPDFlib?PDFlibisalibraryofCroutineswhichallowyoutopro-grammaticallygeneratefilesinAdobeÕsPortableDocumentFormatPDF.PDFlibactsasabackendprocessortoyourownprograms.Whileyou(theprogrammer)areresponsibleforretrievingormaintainingthedatatobeprocessed,PDFlibtakesoverthetaskofgeneratingthePDFcodewhichgraphicallyrepresentsyourdata.Whileyoumuststillformatandarrangeyourtextandgraphicalobjects,PDFlibfreesyoufromtheinternalsandin-tricaciesofPDF.Althoughbeingfarfromcomplete,PDFlibalreadyoffersmanyusefulfunctionsforcreatingtext,graphics,imagesandhypertextel-ementsinPDFfiles.PDFlibfeatures.ThePDFlibAPIoffersthefollowingmajorfeatures:PDFdocumentsofarbitrarylengthandpageformatstextoutputindifferentfontstheabilitytoembedPostScriptfontdescriptionscommonvectorgraphicsprimitivesÐlines,curves,arcs,rectangles,etc.readPostScriptfontmetricsfromAFMfilesprocesscommongraphicsfileformats,e.g.TIFF,GIF,JPEGgeneratehypertextelementssuchasbookmarksfeaturessupportedinPDFbutnotaccessibleinAcrobatsoftware,e.g.,pagetransitioneffectslikeshadesandmosaic.AllofthesemaybeachievedbyusingasimpleAPIwithouttheapplicationprogrammerbeingdirectlyinvolvedwithPDFobjectsoroperators.WhatcanIusePDFlibfor?PDFlibÕsprimarytargetiscreatingdynamicPDFontheWorldWideWeb.SimilartoHTMLpagesdynamicallygeneratedwithaCGIscriptontheWebserver,youmayuseaPDFlibprogramfordy-namicallygeneratingPDFreflectinguserinputorsomeotherdynamicda-ta,e.g.dataretrievedfromtheWebserverÕsdatabase.ThePDFlibapproachoffersseveraladvantagesasopposedtocreatingPDFfromPostScriptfileswithAcrobatDistiller:ThePDFlibÈdriverÇcanbeintegrateddirectlyintheapplicationgenerat-ing(orotherwisehandling)thedata,eliminatingtheconvolutedcre-ationpathapplicationÐPostScriptÐAcrobatDistillerÐPDF.Asanimplicationofthisstraightforwardprocess,PDFlibisbyfarthefastestPDF-generatingmethod,makingitperfectlysuitedfortheWeb.PDFsneednotbecreatedaheadoftimeandstoredontheserver,butcanbegeneratedifneeded.ThisisabigwinnotonlyifyouwanttodealwithdynamicdatawhichdonotexistpriortotheWebinteraction,butalsoiflargeamountsofdatahavetobehandledwhichmakeitimpracticaltopre-generateallthenecessaryPDF.6Chapter1:IntroductionHowever,PDFlibisnotrestrictedtodynamicPDFontheWeb.Equallyim-portantareallkindsofconvertersfromXtoPDF,whereXrepresentsanytextorgraphicsfileformat.Again,thisreplacesthesequenceXÐPostScriptÐPDFwithsimplyXÐPDF,whichoffersmanyadvantagesforsomecommongraphicsfileformatslikeGIForJPEG.UsingsuchaPDFconverter,batchconvertinglotsoftextorgraphicsfilesismucheasierthanusingtheAdobeAcrobatsuiteofprograms.Severalconvertersofthiskindaresuppliedwiththelibrary.Whichplatformsaresupported?PDFlibisaportableANSIClibrarywhichmaybeusedonanyreasonableoperatingsystemplatform.AlthoughbeingdevelopedandtestedonUnixandWindowsNTsystems,thelibrarydoesnotdependonanyUnixspecificfeaturesandmaywellbeusedonotherplatforms.Actually,sincethelibrarydoesnÕtneedanyuserinterface,port-ingtootherplatformsissimplyamatterofarrangingasuitablebuildpro-cess.Thesuppliedlibraryclients,however,useUnix-stylecommandlineoptionswhichmaynotbeconsideredappropriateforotherplatforms.Scriptingsupport.PDFlibnotonlyoffersanANSICprogramminginter-facebutmayalsobeusedfromwithinscriptinglanguages.CurrentlyPerl,Tcl,andPythonaresupported.YoucancallPDFlibroutines(asdescribedinthismanual)fromyourPerl,Tcl,orPythonscripts.ThisgreatlysimplifiestheprocessofwritingusefulPDF-generatingapplicationsorscripts.RequirementsforusingPDFlib.PDFlibtriestomakepossiblePDFgenera-tionwithoutwadingthroughthe400pagePDFspecification.WhilePDFlibtriestohidetechnicalPDFdetailsfromtheuser,ageneralunderstandingofPDFishighlydesirable.InordertomakethebestuseofPDFlib,applicationprogrammersshouldbefamiliarwiththegraphics