txt: ## dist_zef-dwarring-PDF-API6.md
  ## Chunk 3 of 3
   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. |
  
  ### 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 `(Numeric, Numeric)` 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: Text Rendering Modes
  
  Text is filled using the current `FillColor` and/or stroked using the
  current `StrokeColor`, depending on the current `TextRender` mode
  as listed below.
  
  Enumerations can be imported via `use PDF::Content::Ops :TextMode`
  
  | 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. |
  
  ## Appendix III: 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*.
  
  1. *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*.
  
  1. *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.
  