### ----------------------------------------------------
### -- PDF::API6
### -- Licenses: Artistic-2.0
### -- Authors: David Warring
### -- File: README.md
### ----------------------------------------------------
### -- Chunk 3 of 3
 colour spaces, three operands. DeviceCMYK has four operands.
SetStrokeColorN(c1, ..., cn [,pattern-name]) | SCN | Same as SetStrokeColor but also supports Pattern, Separation, DeviceN, ICCBased colour spaces and patterns.
SetFillColor(c1, ..., cn) | sc | Same as SetStrokeColor, but for non-stroking operations.
SetFillColorN(c1, ..., cn [,pattern-name]) | scn | Same as SetStrokeColorN, but for non-stroking operations.
SetStrokeGray(level) | G | Set the stroking colour space to DeviceGray and set the gray level to use for stroking operations, between 0.0 (black) and 1.0 (white).
SetFillGray(level) | g | Same as G but used for non-stroking operations.
SetStrokeRGB(r, g, b) | RG | Set the stroking colour space to DeviceRGB and set the colour to use for stroking operations. Each operand is a number between 0.0 (minimum intensity) and 1.0 (maximum intensity).
SetFillRGB(r, g, b) | rg | Same as RG but used for non-stroking operations.
SetFillCMYK(c, m, y, k) | K | Set the stroking colour space to DeviceCMYK and set the colour to use for stroking operations. Each operand is a number between 0.0 (zero concentration) and 1.0 (maximum concentration). The behaviour of this operator is affected by the OverprintMode graphics state.
SetStrokeCMYK(c, m, y, k) | k | Same as K but used for non-stroking operations.

### Graphics State

Method | Code | Description | Notes
--- | --- | --- | ---
Save() | q | Save the current graphics state on the graphics state stack | [1]
Restore() | Q | Restore the graphics state by removing the most recently saved state from the stack and making it the current state. | [1]
ConcatMatrix(a, b, c, d, e, f) | cm | Modify the current transformation matrix (CTM) by concatenating the specified matrix | [2]
SetLineWidth(width) | w | Set the line width in the graphics state
SetLineCap(cap-style) | J | Set the line cap style in the graphics state (see LineCap enum)
SetLineJoin(join-style) | j | Set the line join style in the graphics state (see LineJoin enum)
SetMiterLimit(ratio) | M | Set the miter limit in the graphics state
SetDashPattern(dashArray, dashPhase) | d | Set the line dash pattern in the graphics state
SetRenderingIntent(intent) | ri | Set the colour rendering intent in the graphics state: AbsoluteColorimetric, RelativeColormetric, Saturation, or Perceptual
SetFlatness(flat) | i | Set the flatness tolerance in the graphics state. flatness is a number in the range 0 to 100; 0 specifies the output device’s default flatness tolerance.
SetGraphics(dictName) | gs | Set the specified parameters in the graphics state. dictName is the name of a graphics state parameter dictionary in the ExtGState resource sub-dictionary | [3]

[1] See also the [graphics](#graphics) method

[2] See also the [transform](#transform) method

[3] See also [Advanced State Variables](#general-graphics---advanced-state-variables)

### Text Operators

Method | Code | Description | Notes
--- | --- | --- | ---
BeginText() | BT | Begin a text object, initializing $.TextMatrix, to the identity matrix. Text objects cannot be nested. | [1]
EndText() | ET | End a text object, discarding the text matrix. | [1]
TextMove(tx, ty) | Td | Move to the start of the next line, offset from the start of the current line by (tx, ty ); where tx and ty are expressed in unscaled text space units. | [2]
TextMoveSet(tx, ty) | TD | Move to the start of the next line, offset from the start of the current line by (tx, ty ). Set $.TextLeading to ty.
SetTextMatrix(a, b, c, d, e, f) | Tm | Set $.TextMatrix | [3]
TextNextLine| T* | Move to the start of the next line
ShowText(string) | Tj | Show a text string | [4][5]
MoveShowText(string) | ' | Move to the next line and show a text string. | [4][5]
MoveSetShowText(aw, ac, string) | " | Move to the next line and show a text string, after setting $.WordSpacing to  aw and $.CharSpacing to ac | [4][5]
ShowSpacetext(array) |  TJ | Show one or more text strings, allowing individual glyph positioning. Each element of array is either a string or a number. If the element is a string, show it. If it is a number, adjust the text position by that amount | [4][5]

[1] See also the [text](#text) method

[2] See also the [text-position](#text-position) method

[3] See also the [text-transform](#text-transform) method

[4] See also the [print](#print) and [say](#say) methods

[5] `string` arguments should be encoded using the current font. For example:

    $gfx.ShowText: $gfx.font.encode("Sample Text", :str)

### Path Construction Operators

Method | Code | Description | Notes
--- | --- | --- | ---
MoveTo(x, y) | m | Begin a new sub-path by moving the current point to coordinates (x, y), omitting any connecting line segment. If the previous path construction operator in the current path was also m, the new m overrides it. | [1]
LineTo(x, y) | l | Append a straight line segment from the current point to the point (x, y). The new current point is (x, y). | [1]
CurveTo(x1, y1, x2, y2, x3, y3) | c | Append a cubic Bézier curve to the current path. The curve extends from the current point to the point (x3, y3 ), using (x1 , y1 ) and (x2, y2 ) as the Bézier control points. The new current point is (x3, y3 ). | [1]
Rectangle(x, y, width, Height) | re | Append a rectangle to the current path as a complete sub-path, with lower-left corner (x, y) and dimensions `width` and `height`. | [1]
ClosePath | h | Close the current sub-path by appending a straight line segment from the current point to the starting point of the sub-path. | [1]

[1] The [current-point](#method-current-point) accessor can be used to obtain the Current Point.

### Path Painting Operators

Method | Code | Description | Notes
--- | --- | --- | ---
Stroke() | S | Stroke the path. | [1]
CloseStroke() | s | Close and stroke the path. Same as: $.ClosePath; $.Stroke | [1]
Fill() | f | Fill the path, using the nonzero winding number rule to determine the region. Any open sub-paths are implicitly closed before being filled. | [1]
EOFill() | f* | Fill the path, using the even-odd rule to determine the region to fill | [1]
FillStroke() | B | Fill and then stroke the path, using the nonzero winding number rule to determine the region to fill. | [1]
EOFillStroke() | B* | Fill and then stroke the path, using the even-odd rule to determine the region to fill. | [1]
CloseFillStroke() | b | Close, fill, and then stroke the path, using the nonzero winding number rule to determine the region to fill. | [1]
CloseEOFillStroke() | b* | Close, fill, and then stroke the path, using the even-odd rule to determine the region to fill. | [1]
EndPath() | n | End the path object without filling or stroking it. This operator is a path-painting no-op, used primarily for the side effect of changing the current clipping path. | [1]

[1] See also [paint](#paint) method, which encapsulates the operators in this section. For example:

    $gfx.paint(:close, :fill, :stroke);   # equivalent to $gfx.CloseFillStroke
    $gfx.paint(:close, :fill);            # equivalent to $gfx.ClosePath; $gfx.Fill

### Path Clipping

Method | Code | Description
 --- | --- | ---
Clip() | W | Modify the current clipping path by intersecting it with the current path, using the nonzero winding number rule to determine which regions lie inside the clipping path. |
EOClip() | W* | Modify the current clipping path by intersecting it with the current path, using the even-odd rule to determine which regions lie inside the clipping path. |

The current clipping path is applied to the next painting or text output
operation. For example:

```raku
given $gfx {
    .Rectangle: 100, 100, 125, 20;
    .Clip;
    .EndPath;
    .say: 'Clip me', :position[98, 98];
}
```

### Marked Content

Method | Code | Description | Notes
--- | --- | --- | ---
MarkPoint(tag) | MP | Designate a marked-content point. | [1]
MarkPointDict(tag,props) | DP | Designate a marked-content point with an associated property dictionary. | [1]
BeginMarkContent(tag) | BMC |  Begin a marked-content sequence terminated by a balancing `EMC` (EndMarkedContent) operator. | [1]
BeginMarkedContentDict(tag,props) |  BDC |  Begin a marked-content sequence with an associated property dictionary | [1]
EndMarkContent | EMC | End a marked-content sequence begun by a BMC (BeginMarkedContent) or BDC (BeginMarkedContentDict) operator. | [1]

[1] See also  [tag](#tag) and [mark](#mark) methods

### Graphics Introspection Methods


#### Method graphics-state()

Synopsis: `my %gstate = $gfx.graphics-state: :delta`

Returns a snapshot of the current graphics state. Summarising the values of all of the graphics variables described above. The `:delta` option returns only those values that have been updated since the last `.Save()` ('q' operator).

#### Method gsaves()

Synopsis: `my Hash @gstates = $gfx.gsaves: :delta`

A summary of all currently saved graphics states. This corresponds to the the number of open Save ('q') operations that have not been closed with a Restore ('Q') operation.

The `:delta` option returns the differences from the current graphics state to the last gsave, and the difference between each previously saved graphics state.

#### Method context()

Synopsis: `my $ctxt  = $gfx.context()`

Returns the current graphics state context. As defined in the PDF::Content::Ops::GraphicsContext enumeration. One of: Path, Text, Clipping, Page, Shading or Image.

#### Method ops()

Synopsis: `my Pair @ops = $gfx.ops(); PDF::IO::Writer.write-content(@ops);`

Returns a raw list of operations to date.

#### Method content-dump()

Synopsis: `my Str @lines = .content-dump()`

Returns a serialized content stream to-date as a list of lines

#### Method open-tags()

Synopsis: `my PDF::Content::Tag @tags = .open-tags();`

Returns any currently open marked-content tags.

#### Method tags()

Synopsis: `my PDF::Content::Tag @closed-tags = .tags()`

Returns previously closed marked content tags

### Method current-point()

Returns the Current Point coordinates during path construction, as a two element list (`x` and `y`). Returns `List:U` if a path is not being constructed.

### Graphics Tracing

The `gfx :trace` option enables tracing as graphics operations are executed. For example:

    use PDF::API6;
    use PDF::Page;
    use PDF::Content;
    my PDF::API6 $pdf .= new;
    my PDF::Page $page = $pdf.add-page;
    my PDF::Content $gfx = $page.gfx: :trace;
    $gfx.text: {
        .font = $pdf.core-font: 'Times-Roman';
        .print: "Hello World";
    };

Produces:

    BT	% BeginText
      /F1 16 Tf	% SetFont	{"Font":[{"BaseFont":"Courier","Encoding":"WinAnsiEncoding","Subtype":"Type1","Type":"Font"},16]}
      (Hello World) Tj	% ShowText
    ET	% EndText

To break this down:
- The `text()` method is adding a BeginText (BT) graphics operation
  on block entry and a EndText (ET) method on exit.
- The `font()` method sets the current font object and size. Behind the scenes it has also set up a font dictionary, registered as /F1 for the font
- The `print()` command is displaying text using thew ShowText (Tj) operator

The following methods give an overview of the current state of the graphics engine:

## Appendix II: Enumerations

### Text Rendering Modes

```raku
use PDF::Content::Ops :TextMode;
$gfx.text: {
    .TextRender = TextMode::OutlineText;
    .say: "Outlined";
    # ...
}
```
Text is filled using the current `FillColor` and/or stroked using the
current `StrokeColor`, depending on the current `TextRender` mode
as listed below.

Mode | Enumeration | Description
---- | ----------- | -----------
0 | FillText | Fill text (default).
1 | OutlineText | Stroke text.
2 | FillOutlineText | Fill, then stroke text.
3 | InvisableText | Neither fill nor stroke text (invisible).
4 | FillClipText | Fill text and add to path for clipping
5 | OutlineClipText | Stroke text and add to path for clipping.
6 | FillOutlineClipText | Fill, then stroke text and add to path for clipping.
7 |ClipText | Add text to path for clipping.

### Line Cap Enumerations

```raku
use PDF::Content::Ops :LineCaps;
$gfx.LineCap = LineCaps::SquareCaps;
```

Mode | Enumeration | Description
---- | ----------- | -----------
0 | ButtCaps | Square ends (default)
1 | RoundCaps | Semicircular ends
2 | SquareCaps | Squared and projected a half line-width

### Line Join Enumerations

```raku
use PDF::Content::Ops :LineJoin;
$gfx.LineJoin = LineJoin::RoundJoin;
```
Mode | Enumeration | Description
---- | ----------- | -----------
0 | MiterJoin | Fully extended joins (default)
1 | RoundJoin | Rounded joins
2 | BevelJoin | Truncated joins (similar to ButtCaps)

## Appendix III: Text Block Special Characters

The following Unicode characters can be used to control
layout and formatting by the [print](#print) and [say](#say) methods.

### Spacing characters

Character | Description
--------- | -----------
\c[SPACE] | Regular space
\c[EN SPACE]  | .5 EM
\c[EM SPACE]  | 1 EM
\c[THREE-PER-EM SPACE] | 3 EM
\c[FOUR-PER-EM SPACE] | 4 EM
\c[SIX-PER-EM SPACE] | 6 EM
\c[THIN SPACE] | .2 EM
\c[HAIR SPACE] | .1 EM

### Line breaking control

Character | Description | Usage
--------- | ----------- | -----
\n | Logical new-line | line-break in `:verbatum` mode, regular space otherwise
\c[NO-BREAK SPACE] \c[NARROW NO-BREAK SPACE] | Regular and narrow non-breaking spaces |
\c[HYPHEN] \c[HYPHEN-MINUS] | regular hyphenation |
\c[HYPHENATION POINT] | Potential hyphenation point within a word |
\c[ZERO WIDTH SPACE] | Potential non-hyphenating word breaks |

### Bidi Control

A number of [Unicode bidirectional control](https://www.w3.org/International/questions/qa-bidi-unicode-controls.en) (BiDi) characters are enabled, if the [Text::FriBidi](https://raku.land/zef:dwarring/Text::FriBidi) is installed.

Bidi control character include \c[LEFT-TO-RIGHT EMBEDDING],
\c[RIGHT-TO-LEFT EMBEDDING], \c[POP DIRECTIONAL FORMATTING] and
other characters in the ranges x2066..x2069 and x202A..x202E.

The `:!bidi` option can be  been used to disable BiDi processing, or to silence warnings if [Text::FriBidi](https://raku.land/zef:dwarring/Text::FriBidi) is not installed.

## Appendix IV: Module Overview


                               PDF::API6
                                  ^
                                  |
                                  |
    3.       PDF::Lite         PDF::Class
                |                 |
                |                 | ..<... PDF::Tags
                |                 |
                +-----------------+
                        ^
    2.                  | --<--- PDF::Content
                        |
                        | ..<... PDF::Font::Loader
                        |
                        ^                FDF
                        |                 |
                        +-----------------+
                        |
    1.                 PDF
                        |
                        | --<--- PDF::Grammar


There are three levels underlying PDF::API6. From bottom to top, these are:

1. *PDF* handles the
physical structure of a PDF, including object indexes, encryption, data
dictionaries and arrays and the packing and unpacking of stream content.
PDF files can be created read and updated.

As well as loading PDF files, the *PDF* module can load FDF files, which are
a closely related, but simpler format with the same syntax, commonly used to maintain
form data associated with a PDF. There is an unreleased *FDF* module than is analogous to, but much simpler than *PDF::Class*.

2. *PDF::Content* is a set of roles that both *PDF::Class* and
*PDF::Lite* use to implement basic PDF content and graphics.
This includes methods for page manipulation, images, xobject forms, graphics,
simple colors (RGB, CMYK and Gray-scale) and core-fonts.

The optional *PDF::Font::Loader* can be used to load Type-1 and Free-Type fonts
for use by either *PDF::Class*, or *PDF::Lite*.

3. *PDF::Class* is a comprehensive set of classes that understand most of
the commonly used objects in a PDF, including fonts, interactive features, tagged
PDF, AcroForm fields and annotations.

*PDF::Lite* understands content only, including pages and xobjects (forms and images). 

The optional *PDF::Tags* module is applicable to PDF files that are 'Tagged'. It
presents a DOM like interface for reading document structure elements.

*PDF::API6* is a lightweight class that inherits from *PDF::Class*. It provides
sugar and extra functionality for common use cases such as colors, outlines
(table of contents) and preferences.



