LibHaruCore 1.0.1

LibHaruCore

Modern .NET bindings and a high-level API for the libharu PDF library, Windows-first.

• Low-level: thin, per-header P/Invoke bindings under LibHaruCore.Bindings.HpdfBindings with opaque handle structs (HPDF_*).
• High-level: ergonomic API in LibHaruCore.HighLevel (PdfDocument, PdfPage, PdfImage, PdfOutline, PdfExtGState). UTF‑8 by default, exceptions on errors.
• Demos: side-by-side low-level and high-level examples in demo/LibHaruDemos.

Features

High-level API highlights:

• Document: metadata, viewer preferences, destinations, outlines, encryption, attachments, open action.
• Pages: text/layout helpers, shapes and paths, colors (RGB/Gray/CMYK), images (PNG/JPEG/raw RGB), transitions.
• Annotations: text, free text (callouts), highlight/underline/squiggly/strikeout, popup, stamp, link (URI/destination/JavaScript), line, square, circle.
• ExtGState: alpha and blend mode via PdfExtGState with a simple CreateExtGState() factory.
• RAII helpers: using var _ = page.TextBlock() and using (page.SaveState()) { ... }.
• Diagnostics & capabilities: DiagnosticsEnabled, optional Logger (ILogger), SupportsPng, SupportsExtGState.

Low-level API:

• Raw bindings mirror libharu functions and common structs.
• UTF‑8 helpers provide safe string marshaling.

Quick start (high-level)

Create a document, add a page, write text, draw shapes, and save:

using var doc = new PdfDocument();
doc.Title = "Hello PDF";
var page = doc.AddPage();
page.SetSize(HPDF_PageSizes.HPDF_PAGE_SIZE_LETTER, HPDF_PageDirection.HPDF_PAGE_PORTRAIT);

using (page.SaveState())
{
	using var _t = page.TextBlock();
	page.SetFontAndSize("Helvetica", 24);
	page.TextOut(72, 720, "Hello from High-Level API");
}

page.SetStrokeRGB(0.2f, 0.2f, 0.8f);
page.SetLineWidth(2);
page.Rectangle(70, 680, 300, 40);
page.Stroke();

doc.Save("out.pdf");

Images

• PNG/JPEG from file: doc.LoadPng(path) / doc.LoadJpeg(path).
• Raw RGB from memory: doc.LoadRawRgb(byte[]|ReadOnlySpan<byte>, width, height, bitsPerComponent).

var img = doc.LoadJpeg("photo.jpg");
page.DrawImageFit(img, 72, 72, 300, 300);

Annotations

page.CreateHighlightAnnot(80, 685, 250, 705, "Highlighted");
page.CreateUriLink(80, 655, 250, 675, "https://example.com",
	highlight: HPDF_AnnotHighlightMode.HPDF_ANNOT_INVERT_BOX, borderWidth: 2f);
page.CreateTextNote(360, 655, 380, 675, "Sticky", HPDF_AnnotIcon.HPDF_ANNOT_ICON_NOTE, true);

Outlines and destinations

var root = doc.CreateOutline(null, "Root");
var p2 = doc.AddPage();
root.SetDestinationToPageTop(page);
var child = doc.CreateOutline(root, "Second Page");
child.SetDestinationFitBH(p2, p2.Height - 100);

Colors and ExtGState

page.SetFillCMYK(0, 0.5f, 1, 0);
if (doc.SupportsExtGState)
{
	var gs = doc.CreateExtGState();
	gs.SetAlphaFill(0.5f);
	page.SetExtGState(gs);
}

Saving

• To file path: doc.Save("file.pdf")
• To a Stream: doc.Save(stream)
• To bytes: var bytes = doc.SaveToBytes();

Diagnostics and capabilities

doc.DiagnosticsEnabled = true; // Console.Error
// or
// doc.Logger = new Microsoft.Extensions.Logging.Abstractions.NullLoggerFactory().CreateLogger("LibHaruCore");

bool canPng = doc.SupportsPng;
bool canExt = doc.SupportsExtGState;

Low-level API (brief)

Use LibHaruCore.Bindings.HpdfBindings for direct calls:

var hdoc = HpdfBindings.HPDF_New((e,d,u)=>{}, IntPtr.Zero);
var pageHandle = HpdfBindings.HPDF_AddPage(hdoc);
HpdfBindings.HPDF_Page_BeginText(pageHandle);
HpdfBindings.HPDF_Page_SetFontAndSize(pageHandle, HpdfBindings.HPDF_GetFont(hdoc, "Helvetica", null), 12);
HpdfBindings.HPDF_Page_TextOut(pageHandle, 72, 720, "Hello low-level");
HpdfBindings.HPDF_Page_EndText(pageHandle);
HpdfBindings.HPDF_SaveToFile(hdoc, "lowlevel.pdf");
HpdfBindings.HPDF_Free(hdoc);

Building and running demos

• Build the solution and run the demos project (choose a single TF):

dotnet build .\LibHaruCore.sln -c Debug

dotnet run -c Debug --framework net8.0 --project .\demo\LibHaruDemos\LibHaruDemos.csproj

The demos output PDFs into the demos bin folder.

License

libharu is ZLIB/LIBPNG; this wrapper is MIT.