Module printpdf::types::plugins::graphics::extgstate

Extended graphics state, for advanced graphical operation (overprint, black point control, etc.)

Some of the operations can be done on the layer directly, but for advanced graphics, you need to set the graphics state. A PDF has an internal default graphics state, which can be reset to by setting ExtendedGraphicsState::default() as the active gs dictionary. Setting a new graphics state overwrites the old one, there is no "undo".

In order to use a graphics state, it must be added to the Pages resource dicitionary. This is done by the layer.set_graphics_state() function, which returns a reference with the name of the newly added dictionary. From inside a stream, the graphics state parameter is invoked with the "gs" command using the name of the graphics state as a operator. This is done using the layer.use_graphics_state().

A full graphics state change is done like this:

let mut new_state = ExtendedGraphicsState::default();
new_state.overprint_stroke = true;

// it is best to put the next lines in a seperate function
// A PdfLayerReferences contains the indices of the page and the layer
// as well as a `std::sync::Weak` reference to the document.
// This is why you need the braces, otherwise, you'll trigger a deadlock
{
    // supposing mylayer is a PdfLayerReference
    let doc = mylayer.document.upgrade().unwrap();
    let mut doc = doc.lock().unwrap();
    let mut page = doc.pages.get_mut(self.page.0).unwrap();

    // see the documentation for add_graphics_state
    page.add_graphics_state(new_state);
}

Structs

ExtendedGraphicsState	ExtGState dictionary
ExtendedGraphicsStateBuilder
ExtendedGraphicsStateList	List of many ExtendedGraphicsState
ExtendedGraphicsStateRef	A reference to the graphics state, for reusing the graphics state during a stream without adding new graphics states all the time
LineDashPattern	Line dash pattern is made up of a total width
SoftMask	A soft mask is used for transparent images such as PNG with an alpha component The bytes range from 0xFF (opaque) to 0x00 (transparent). The alpha channel of a PNG image have to be sorted out. Can also be used for Vignettes, etc. Beware of color spaces! See PDF Reference Page 545 - Soft masks

Enums

BlackGenerationExtraFunction
BlackGenerationFunction	Black generation calculates the amount of black to be used when trying to reproduce a particular color.
BlendMode
HalftoneType	In PDF 1.2, the graphics state includes a current halftone parameter, which determines the halftoning process to be used by the painting operators. It may be defined by either a dictionary or a stream, depending on the type of halftone; the term halftone dictionary is used generically throughout this section to refer to either a dictionary object or the dictionary portion of a stream object. (The halftones that are defined by streams are specifically identified as such in the descriptions of particular halftone types; unless otherwise stated, they are understood to be defined by simple dictionaries instead.) Deserialized into Integer: 1, 5, 6, 10 or 16
LineCapStyle	See PDF Reference (Page 216) - Line cap (ending) style
LineJoinStyle	See PDF Reference Page 216 - Line join style
NonSeperableBlendMode	Since the nonseparable blend modes consider all color components in combination, their computation depends on the blending color space in which the components are interpreted. They may be applied to all multiple-component color spaces that are allowed as blending color spaces (see Section 7.2.3, “Blending Color Space”).
OverprintMode	(PDF 1.3) A code specifying whether a color component value of 0 in a DeviceCMYK color space should erase that component (EraseUnderlying) or leave it unchanged (KeepUnderlying) when overprinting (see Section 4.5.6, “Over- print Control”). Initial value: EraseUnderlying
RenderingIntent	Although CIE-based color specifications are theoretically device-independent, they are subject to practical limitations in the color reproduction capabilities of the output device. Such limitations may sometimes require compromises to be made among various properties of a color specification when rendering colors for a given device. Specifying a rendering intent (PDF 1.1) allows a PDF file to set priorities regarding which of these properties to preserve and which to sacrifice.
SeperableBlendMode	PDF Reference 1.7, Page 520, Table 7.2 Blending modes for objects In the following reference, each function gets one new color (the thing to paint on top) and an old color (the color that was already present before the object gets painted)
SoftMaskFunction
SpotFunction	Spot functions, Table 6.1, Page 489 in Pdf Reference v1.7 The code is pseudo code, returning the grey component at (x, y).
TransferExtraFunction
TransferFunction
UnderColorRemovalExtraFunction
UnderColorRemovalFunction	See BlackGenerationFunction, too. Undercolor removal reduces the amounts of the cyan, magenta, and yellow components to compensate for the amount of black that was added by black generation.