libharu — the Haru Free PDF Library — dates back to 1999, is zlib-licensed and speaks fluent PDF: TrueType and Type1 fonts, JPEG and PNG images, links and annotations, outlines, RC4 encryption, even PDF/A-3 with a Factur-X payload. What it does not speak is PureBasic, and a C header is not an API until something binds it.
hpdf.pbi is that something. One include for PureBasic 6.40, three DLLs beside the exe,
and a deliberate refusal to involve the linker: every function is bound at runtime
through OpenLibrary() + GetFunction() + Prototypes. The whole
package — wrapper, module, DLL sets and the 24 ported samples — is free to use and lives
on GitHub:
tureluut/pb-wrapper-libharu.
Bound at runtime, checked at init
The obvious route is a link-time import: declare the functions, hand the linker an
import library, ship. The wrapper takes the runtime route instead, and the reasons are
all operational. The DLLs can live anywhere —
HaruInit("libraries/windows/x64/") points at them, or pass
nothing and the exe directory is searched first. A wrong or truncated DLL is not
rewarded with a cryptic linker error or a mid-run crash: HaruInit() binds
every export, counts what succeeded and lists what did not. If a single one is missing,
it closes everything and returns 0 — there is no half-bound state to fall into.
Macro HaruBind(fn, fns)
fn = GetFunction(HaruLib, fns)
If fn = 0
HaruMissing$ = HaruMissing$ + fns + " " # diagnostics, not crashes
Else
HaruBound + 1
EndIf
EndMacro
HaruBind(HPDF_Page_TextOut, "HPDF_Page_TextOut")
HaruBind(HPDF_Page_TextOutRaw, "HPDF_Page_TextOut") # same export, raw char*
One Windows subtlety earns its comment block. hpdf.dll itself imports
zlib.dll and libpng16.dll; when those live outside the default
search path, the loader can bind hpdf and still fail to resolve its imports. So
HaruInit(dir$) opens zlib and libpng first — Windows reuses
already-loaded modules by name when it resolves hpdf’s imports, and the dependency
question answers itself.
The same include compiles on Linux unchanged. Prototypes and
GetFunction() are cross-platform, so only the loader branches:
dlopen has no exe-directory search, so that path is resolved via
ProgramFilename(), the current directory needs an explicit
./ prefix, and libhpdf.so is tried with and without the
versioned .so.2 suffix that distro runtime packages install. zlib and
libpng need no preload there — ld.so settles dependencies on its own.
Hello, PDF
The lifecycle contract is three lines and non-negotiable: HaruInit() once
before anything else — every HPDF_* name is a function pointer, and calling
a pointer before init dereferences null — then HaruFree() for every
document and HaruShutdown() at exit. Everything in between is ordinary
drawing code:
XIncludeFile "hpdf.pbi"
HaruInit("libraries/windows/x64/") # 0 = fail cleanly; HaruMissing$ says why
Define pdf.i = HaruNew() # UTF-8 pipeline enabled
Define page.i = HaruAddPage(pdf) # A4 portrait
Define font.i = HaruTTFFont(pdf, "C:/Windows/Fonts/arial.ttf") # embedded
HPDF_Page_SetFontAndSize(page, font, 24)
HaruTextOut(page, 72, 750, "Invoice £ 4797,65 — café")
HPDF_SaveToFile(pdf, "out.pdf")
HaruFree(pdf)
HaruShutdown()
The thin Haru* layer exists because a 1:1 C binding alone is not pleasant
to live with. HaruNew() switches on the UTF-8 encodings and sets the UTF-8
encoder, so strings go in as UTF-8 and come out as text.
HaruTextOut() wraps BeginText/EndText around
itself — the raw HPDF_Page_TextOut refuses to run outside a text object, a
gmode detail every C sample handles by hand. HaruTTFFont() caches per
document and path, and quietly retries plain TTFs through the TTC-only export that
libharu 2.4.6 routes them to. HaruAlpha() caches ExtGState objects per
alpha value. None of it hides the library; it removes the three or four places where the
C API punishes the unwary.
Types, kept 1:1 with the header
The include’s header names hpdf.h of 2.4.6 as the source of truth,
and the prototypes obey: 169 of them, one per export, signatures carried over exactly.
The discipline is in the details:
HPDF_REAL (C float) -> .f # never .d — a double silently shifts bits
HPDF_BOOL / STATUS / UINT -> .l # 4-byte C int; explicit .l return
HPDF_UINT16 -> .w
HPDF_*HANDLE -> .i # opaque pointers
const char* in -> .p-ascii # valid for the call only — never store
display-text params -> .p-utf8 # TextOut, TextWidth, TextRect, ...
char* return -> .i + PeekS # pseudotypes are params-only
struct-by-value return -> BANNED # use the ...2 out-param variants
Two rules earn their keep. The explicit .l on every int-returning prototype
is sign-extension hygiene: on x64 the calling convention may leave garbage in the upper
half of rax, and reading eax only keeps a −1 from
turning into 4,294,967,295. And the struct-by-value ban exists because PureBasic
prototypes cannot express C struct returns — so the wrapper standardizes on
libharu’s own out-parameter variants (HPDF_Page_GetCurrentPos2,
HPDF_Image_GetSize2), which deliver identical values through a caller-owned
HPDFPoint. Every sample port that meets one of these substitutions
documents it in its header — numbered, with the reason.
HPDF_ResetError. So the ports drop the handler and gate every save behind
one HPDF_GetError check; HaruErrorText(pdf) formats the pair
as err <hex>/<hex> for diagnostics.
UTF-8 first, WinAnsi where it counts
Text is where C bindings usually fall apart, so this one picks a side: UTF-8 first. The
display-text functions — TextOut, ShowText,
ShowTextNextLine, TextWidth, MeasureText,
TextRect — are bound with .p-utf8, and “café” just
works.
But the base-14 fonts — Helvetica, Times, Courier — are non-embedded and single-byte;
they have no idea what to do with UTF-8. Forcing one encoding onto every call would make
half the library worse. So the same DLL exports are bound twice, once per signature: the
.p-utf8 versions for embedded fonts, and Raw variants taking a
plain char* that pair with HaruWinAnsiMem() — a PB string
turned into a NUL-terminated CP1252 buffer, locale-independent. The CJK sample ports go
further and pass SJIS or GBK bytes straight through, exactly like the C originals.
One source, two shapes
Prefer namespaces? hpdf_module.pbi is the same wrapper inside
DeclareModule HPDF — same 169 pointers, same names, same behavior, with the
library handles, binding macro and caches kept private. It is not a hand-maintained
fork: a 66-line Node script slices hpdf.pbi into a module, emits a Declare
for every Haru* helper, and refuses to run if the source layout drifts.
node tools/generate_hpdf_module.cjs --check fails when the generated file
no longer matches — so an ABI fix lands once and both shapes inherit it. Node is needed
only to regenerate; the PureBasic side never sees it.
Proven, not assumed
A wrapper is a wall of declarations until something calls it. The proof here is
libharu’s own sample corpus: all 24 C files in the samples tree — 23 programs plus
the shared grid_sheet.c helper — ported to PureBasic as standalone console
programs, each header naming its C source, its license and its numbered deviations.
run_all.sh compiles and runs the lot, one PASS/FAIL per sample (exit code
plus output file present); the two samples that need user-supplied font files are
skipped, like their C originals.
And the outputs are checked beyond “it did not crash” — at grep level, against the PDF internals:
encryption.pdf /Encrypt /V 1 /R 2 # 40-bit RC4, owner+user passwords
permission.pdf /Encrypt /V 2 /R 3 /Length 128 # read-only, /P 0
ttfont_demo.pdf /FontFile2, /HPDFAA+PenguinAttack # TrueType really embedded
pdf_a_conformance.pdf XMP + /GTS_PDFA1 + /AFRelationship # PDF/A-3B + Factur-X
slide_show_demo.pdf 17 pages, 32 /Link, /PageMode /FullScreen
That last verified line matters more than it looks: the PDF/A port means XMP metadata
with the two Factur-X extension schemas, an sRGB output intent, an embedded ICC profile
and an attached invoice XML tagged
/AFRelationship /Data — the plumbing an e-invoicing standard actually
demands, exercised from PureBasic rather than from C.
Boring on purpose
-
Fails cleanly, never crashes —
HaruInit()returns 0 when the DLL or a single export is missing;HaruMissing$names the stragglers andHaruBoundcounts the rest. Documents are freed withHaruFree(), which also purges the per-document caches. -
One include, two architectures — the binding code is OS-agnostic; x64 and x86
DLL sets ship in
libraries/windows/, and the loader already knows how to behave on Linux. Nothing outsideHaruInit()branches on platform. -
Version-locked by construction — signatures are declared 1:1 against
hpdf.hof 2.4.6, so a mismatched DLL is caught export-by-export at init, not discovered at runtime. -
Licensed to ship — the wrapper is free to use; the three DLLs carry the
libharu, zlib and libpng licenses, all permitting commercial redistribution, with the
texts collected in
THIRD-PARTY-NOTICES.md.
The binding disappears
The through-line is the one this site keeps arriving at: a binding’s job is to disappear. hpdf.pbi does not build an abstraction over PDF — it expresses the DLL’s own contract once, in PureBasic’s accent, then adds only the handful of helpers the C API cannot express: UTF-8 by default, cached fonts and alphas, honest errors. No import library, no runtime, no generator required to use it. 169 prototypes and three DLLs, and PDF is just another output format.