Expose FPDF_NewFormObjectFromXObject()

[vmiklos]

Merging an entire page from a source document to an existing target page can be a use-case when e.g. printing 2 pages on 1 page.

Copying objects is quite complex in general, but in case all objects of a page is to be copied, pdfium provides a FPDF_NewFormObjectFromXObject() function just for this, which plays nicely with the XObject form object mechanism of the PDF spec.

Add a new create_x_object_form_object() public function to expose this function.

Sample usage to insert the first page of source_doc as an XObject form object into dest_page: dest_page.objects_mut().create_x_object_form_object(&source_doc, 0).unwrap();

Fixes https://github.com/ajrcarey/pdfium-render/issues/181.

[vmiklos]

Fixed 2 typos in comments.

[vmiklos]

Here is a rebased version, mostly following how you updated PdfPageObjects::create_image_object() as an example. It works, but this would be my first PR in the project, so feel free to tweak it the way you like.

Sample playground code to try it out:

• Cargo.toml:

[package]
name = "test"
version = "0.1.0"
edition = "2021"

[dependencies]
pdfium-render = { path = "../pdfium-render" }

• src/main.rs:

use pdfium_render::prelude::*;

fn main() {
    let pdfium = Pdfium::default();
    let mut out_doc = pdfium.create_new_pdf().unwrap();
    let mut out_page = out_doc
        .pages_mut()
        .create_page_at_end(PdfPagePaperSize::a4())
        .unwrap();
    let source_doc = pdfium.load_pdf_from_file("in.pdf", None).unwrap();
    out_page.objects_mut().create_x_object_form_object(&source_doc, 0).unwrap();
    out_doc.save_to_file("out.pdf").unwrap();
}

• in.pdf: in.pdf

[ajrcarey]

Hi @vmiklos , thank you for the excellent contribution. Apologies for the delay in merging; I have just been thinking about the best way to integrate your pull request. I may move it aorund a bit. I aim to include your new feature in crate release 0.8.29.

[vmiklos]

Nice :) Feel free to rework it as you see it necessary. Thanks.

[vmiklos]

@ajrcarey what happened here at the end? If I understand correctly, FPDF_NewFormObjectFromXObject() is still only available once this patch is applied and in the meantime 0.8.29 is out already.

Again, no rush, but if a better version takes this long -- would it make sense to include this PR as-is or with smaller tweaks? Thanks.

With regards to testing, I tested the original 1af90808ab83f7eb464e257376e34c48d5de2ab1 (older baseline) heavily, and I'm reasonably confident in it. Then I had to rebase, I gave that version less testing, though I think that works correctly, too.

[ajrcarey]

The goal is to integrate this functionality into the object group, so that a group can be created from a FormXObject and vice-versa. However, I need some time to figure out exactly what FormXObject operations Pdfium does and does not provide, because I have the impression its support (as in many areas) is only partial.

There are some bug fixes that have to be prioritised first over new functionality. Once those are done, integrating your patch is next on the list of todos.

[vmiklos]

Makes sense, thanks, take your time :)

[ajrcarey]

Work on finalising this functionality will continue as part of #60. Apologies again for the delay on all this.

[vmiklos]

No problem, thanks!