Moved images to pageresources & added xml comments

Author: synercoder

samples/Synercoding.FileFormats.Pdf.ConsoleTester/Program.cs

@@ -1,7 +1,9 @@
 using Synercoding.FileFormats.Pdf.Extensions;
 using Synercoding.FileFormats.Pdf.LowLevel.Graphics;
+using Synercoding.FileFormats.Pdf.LowLevel.Graphics.Colors;
 using Synercoding.Primitives;
 using Synercoding.Primitives.Extensions;
+using System;
 using System.IO;
 
 namespace Synercoding.FileFormats.Pdf.ConsoleTester
@@ -66,26 +68,26 @@ public static void Main(string[] args)
                                 g.Stroke = null;
                                 g.Dash = new Dash()
                                 {
-                                    Array = new double[0],
+                                    Array = Array.Empty<double>(),
                                     Phase = 0
                                 };
                                 g.MiterLimit = 10;
                                 g.LineCap = LineCapStyle.ButtCap;
                                 g.LineJoin = LineJoinStyle.MiterJoin;
                             });
 
-                            ctx.NewPath(g => { g.Fill = Colors.Red; g.Stroke = Colors.Black; g.LineWidth = 5; })
+                            ctx.NewPath(g => { g.Fill = PredefinedColors.Red; g.Stroke = PredefinedColors.Black; g.LineWidth = 5; })
                                 .Move(100, 100)
                                 .LineTo(200, 100)
                                 .LineTo(200, 200)
                                 .LineTo(100, 200);
-                            ctx.NewPath(g => { g.Fill = Colors.Blue; g.Stroke = null; })
+                            ctx.NewPath(g => { g.Fill = PredefinedColors.Blue; g.Stroke = null; })
                                 .Move(50, 50)
                                 .LineTo(150, 50)
                                 .LineTo(150, 150)
                                 .LineTo(50, 150)
                                 .Close();
-                            ctx.NewPath(g => { g.Fill = null; g.Stroke = Colors.Yellow; g.LineWidth = 3; g.Dash = new Dash() { Array = new[] { 5d } }; })
+                            ctx.NewPath(g => { g.Fill = null; g.Stroke = PredefinedColors.Yellow; g.LineWidth = 3; g.Dash = new Dash() { Array = new[] { 5d } }; })
                                 .Move(150, 150)
                                 .LineTo(250, 150)
                                 .LineTo(250, 250)

src/Synercoding.FileFormats.Pdf/Extensions/PdfPageExtensions.cs

@@ -146,7 +146,7 @@ public static PdfPage AddShapes(this PdfPage page, Action<IShapeContext> paintAc
         /// <returns>The same <see cref="PdfPage"/> to chain other calls.</returns>
         public static PdfPage AddShapes<T>(this PdfPage page, T data, Action<T, IShapeContext> paintAction)
         {
-            using (var context = new ShapeContext(page.ContentStream))
+            using (var context = new ShapeContext(page.ContentStream, page.Resources))
                 paintAction(data, context);
 
             return page;

src/Synercoding.FileFormats.Pdf/Extensions/PrimitiveExtensions.cs

@@ -1,9 +1,17 @@
-using Synercoding.Primitives;
+using Synercoding.Primitives;
 
 namespace Synercoding.FileFormats.Pdf.Extensions
 {
+    /// <summary>
+    /// Extension methods for primitives
+    /// </summary>
     public static class PrimitiveExtensions
     {
+        /// <summary>
+        /// Convert a <see cref="Rectangle"/> to a transformation matrix
+        /// </summary>
+        /// <param name="rectangle">The <see cref="Rectangle"/> to use</param>
+        /// <returns>Returns a <see cref="Matrix"/> representing the provided <see cref="Rectangle"/>.</returns>
         public static Matrix AsPlacementMatrix(this Rectangle rectangle)
         {
             rectangle = rectangle.ConvertTo(Unit.Points);

src/Synercoding.FileFormats.Pdf/IPath.cs

@@ -2,22 +2,132 @@
 
 namespace Synercoding.FileFormats.Pdf
 {
+    /// <summary>
+    /// Interface representing a path in the content stream of a page
+    /// </summary>
     public interface IPath
     {
+        /// <summary>
+        /// Begin a new subpath by moving the current point to the coordinates (<paramref name="x"/>, <paramref name="y"/>),
+        /// ommitting any connecting line segment. Appends an (m) operator to the content stream
+        /// </summary>
+        /// <param name="x">The X coordinate of the move</param>
+        /// <param name="y">The Y coordinate of the move</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
         IPath Move(double x, double y);
+
+        /// <summary>
+        /// Begin a new subpath by moving the current point to the coordinates (<paramref name="point"/>),
+        /// ommitting any connecting line segment. Appends an (m) operator to the content stream
+        /// </summary>
+        /// <param name="point">The point to where to move</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
         IPath Move(Point point);
+
+        /// <summary>
+        /// Add a line (l) operator to the content stream
+        /// </summary>
+        /// <param name="x">The X coordinate of the line end point</param>
+        /// <param name="y">The Y coordinate of the line end point</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
         IPath LineTo(double x, double y);
+
+        /// <summary>
+        /// Add a line (l) operator to the content stream
+        /// </summary>
+        /// <param name="point">The point to where to line to</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
         IPath LineTo(Point point);
+
+        /// <summary>
+        /// Add a rectangle (re) operator to the content stream
+        /// </summary>
+        /// <param name="x">The X coordinate of the rectangle</param>
+        /// <param name="y">The Y coordinate of the rectangle</param>
+        /// <param name="width">The width of the rectangle</param>
+        /// <param name="height">The height of the rectangle</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
         IPath Rectangle(double x, double y, double width, double height);
+
+        /// <summary>
+        /// Add a rectangle (re) operator to the content stream
+        /// </summary>
+        /// <param name="rectangle">The rectangle to add to the content stream</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
         IPath Rectangle(Rectangle rectangle);
+
+        /// <summary>
+        /// Append a cubic Bézier curve to the current path. The curve shall extend from the current point to the point (<paramref name="finalX"/>, <paramref name="finalY"/>),
+        /// using (<paramref name="cpX1"/>, <paramref name="cpY1"/>) and (<paramref name="cpX2"/>, <paramref name="cpY2"/>) as the Bézier control points.
+        /// Adds a Cubic Bézier Curve (c) operator to the content stream.
+        /// </summary>
+        /// <param name="cpX1">The X coordinate of the first control point</param>
+        /// <param name="cpY1">The Y coordinate of the first control point</param>
+        /// <param name="cpX2">The X coordinate of the second control point</param>
+        /// <param name="cpY2">The Y coordinate of the second control point</param>
+        /// <param name="finalX">The X coordinate of the endpoint of the curve</param>
+        /// <param name="finalY">The Y coordinate of the endpoint of the curve</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
         IPath CurveTo(double cpX1, double cpY1, double cpX2, double cpY2, double finalX, double finalY);
+
+        /// <summary>
+        /// Append a cubic Bézier curve to the current path. The curve shall extend from the current point to the point (<paramref name="final"/>),
+        /// using (<paramref name="cp1"/>) and (<paramref name="cp2"/>) as the Bézier control points.
+        /// Adds a Cubic Bézier Curve (c) operator to the content stream.
+        /// </summary>
+        /// <param name="cp1">The first control point</param>
+        /// <param name="cp2">The second control point</param>
+        /// <param name="final">The endpoint of the curve</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
         IPath CurveTo(Point cp1, Point cp2, Point final);
-        IPath CurveToWithStartAnker(double cpX1, double cpY1, double finalX, double finalY);
-        IPath CurveToWithStartAnker(Point cp, Point final);
+
+        /// <summary>
+        /// Append a cubic Bézier curve to the current path. The curve shall extend from the current point to the point (<paramref name="finalX"/>, <paramref name="finalY"/>),
+        /// using the current point and (<paramref name="cpX2"/>, <paramref name="cpY2"/>) as the Bézier control points.
+        /// Adds a Cubic Bézier Curve (v) operator to the content stream.
+        /// </summary>
+        /// <param name="cpX2">The X coordinate of the second control point</param>
+        /// <param name="cpY2">The Y coordinate of the second control point</param>
+        /// <param name="finalX">The X coordinate of the endpoint of the curve</param>
+        /// <param name="finalY">The Y coordinate of the endpoint of the curve</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
+        IPath CurveToWithStartAnker(double cpX2, double cpY2, double finalX, double finalY);
+
+        /// <summary>
+        /// Append a cubic Bézier curve to the current path. The curve shall extend from the current point to the point (<paramref name="final"/>),
+        /// using the current point and (<paramref name="cp2"/>) as the Bézier control points.
+        /// Adds a Cubic Bézier Curve (v) operator to the content stream.
+        /// </summary>
+        /// <param name="cp2">The second control point</param>
+        /// <param name="final">The endpoint of the curve</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
+        IPath CurveToWithStartAnker(Point cp2, Point final);
+
+        /// <summary>
+        /// Append a cubic Bézier curve to the current path. The curve shall extend from the current point to the point (<paramref name="finalX"/>, <paramref name="finalY"/>),
+        /// using (<paramref name="cpX1"/>, <paramref name="cpY1"/>) and (<paramref name="finalX"/>, <paramref name="finalY"/>) as the Bézier control points.
+        /// Adds a Cubic Bézier Curve (y) operator to the content stream.
+        /// </summary>
+        /// <param name="cpX1">The X coordinate of the first control point</param>
+        /// <param name="cpY1">The Y coordinate of the first control point</param>
+        /// <param name="finalX">The X coordinate of the endpoint of the curve</param>
+        /// <param name="finalY">The Y coordinate of the endpoint of the curve</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
         IPath CurveToWithEndAnker(double cpX1, double cpY1, double finalX, double finalY);
-        IPath CurveToWithEndAnker(Point cp, Point final);
 
-        IShapeContext Close();
+        /// <summary>
+        /// Append a cubic Bézier curve to the current path. The curve shall extend from the current point to the point (<paramref name="final"/>),
+        /// using (<paramref name="cp1"/>) and (<paramref name="final"/>) as the Bézier control points.
+        /// Adds a Cubic Bézier Curve (y) operator to the content stream.
+        /// </summary>
+        /// <param name="cp1">The first control point</param>
+        /// <param name="final">The endpoint of the curve</param>
+        /// <returns>The calling <see cref="IPath"/> to support chaining operations.</returns>
+        IPath CurveToWithEndAnker(Point cp1, Point final);
 
+        /// <summary>
+        /// Close the <see cref="IPath"/>
+        /// </summary>
+        void Close();
     }
 }

src/Synercoding.FileFormats.Pdf/IShapeContext.cs

@@ -3,10 +3,29 @@
 
 namespace Synercoding.FileFormats.Pdf
 {
+    /// <summary>
+    /// Interface representing a context which can be used to draw shapes on a page
+    /// </summary>
     public interface IShapeContext
     {
+        /// <summary>
+        /// Change the default graphics state
+        /// </summary>
+        /// <param name="configureState">Action used to configure the <see cref="GraphicsState"/></param>
+        /// <returns>The calling <see cref="IShapeContext"/> to support chaining</returns>
         IShapeContext DefaultState(Action<GraphicsState> configureState);
+
+        /// <summary>
+        /// Start a new <see cref="IPath"/>
+        /// </summary>
+        /// <returns>The new <see cref="IPath"/> object to chain pathing operators</returns>
         IPath NewPath();
+
+        /// <summary>
+        /// Start a new <see cref="IPath"/> with a different graphics state
+        /// </summary>
+        /// <param name="configureState">The action used to change the <see cref="GraphicsState"/></param>
+        /// <returns>The new <see cref="IPath"/> object to chain pathing operators</returns>
         IPath NewPath(Action<GraphicsState> configureState);
     }
 }

src/Synercoding.FileFormats.Pdf/Image.cs

@@ -1,12 +1,15 @@
-using SixLabors.ImageSharp;
+using SixLabors.ImageSharp;
 using Synercoding.FileFormats.Pdf.LowLevel;
 using Synercoding.FileFormats.Pdf.LowLevel.Extensions;
 using System;
 using System.IO;
 
 namespace Synercoding.FileFormats.Pdf
 {
-    public class Image : IPdfObject, IDisposable
+    /// <summary>
+    /// Class representing an image inside a pdf
+    /// </summary>
+    public sealed class Image : IPdfObject, IDisposable
     {
         private readonly Stream _imageStream;
         private readonly int _width;

src/Synercoding.FileFormats.Pdf/Internals/Map.cs

@@ -1,3 +1,4 @@
+using System;
 using System.Collections;
 using System.Collections.Generic;
 
@@ -37,7 +38,7 @@ IEnumerator IEnumerable.GetEnumerator()
         public Indexer<T1, T2> Forward { get; }
         public Indexer<T2, T1> Reverse { get; }
 
-        public sealed class Indexer<T3, T4>
+        public sealed class Indexer<T3, T4> : IReadOnlyDictionary<T3, T4>
             where T3 : notnull
             where T4 : notnull
         {
@@ -54,8 +55,26 @@ public T4 this[T3 index]
                 set => _dictionary[index] = value;
             }
 
+            public IEnumerable<T3> Keys => _dictionary.Keys;
+
+            public IEnumerable<T4> Values => _dictionary.Values;
+
+            public int Count => _dictionary.Count;
+
             public bool Contains(T3 value)
                 => _dictionary.ContainsKey(value);
+
+            public bool ContainsKey(T3 key)
+                => _dictionary.ContainsKey(key);
+
+            public IEnumerator<KeyValuePair<T3, T4>> GetEnumerator()
+                => _dictionary.GetEnumerator();
+
+            public bool TryGetValue(T3 key, out T4 value)
+                => throw new InvalidOperationException("TryGetValue is not supported on types with non-nullable values.");
+
+            IEnumerator IEnumerable.GetEnumerator()
+                => _dictionary.GetEnumerator();
         }
     }
 }

src/Synercoding.FileFormats.Pdf/Internals/Path.cs

@@ -1,5 +1,6 @@
 using Synercoding.FileFormats.Pdf.LowLevel;
 using Synercoding.FileFormats.Pdf.LowLevel.Graphics;
+using Synercoding.FileFormats.Pdf.LowLevel.Graphics.Colors;
 using Synercoding.FileFormats.Pdf.LowLevel.Operators.Color;
 using Synercoding.FileFormats.Pdf.LowLevel.Operators.Pathing.Construction;
 using Synercoding.FileFormats.Pdf.LowLevel.Operators.Pathing.Painting;
@@ -11,12 +12,10 @@ namespace Synercoding.FileFormats.Pdf.Internals
 {
     internal class Path : IPath
     {
-        private readonly ShapeContext _context;
         private readonly ContentStream _contentStream;
 
-        public Path(ShapeContext context, ContentStream contentStream, GraphicsState graphicsState)
+        public Path(ContentStream contentStream, GraphicsState graphicsState)
         {
-            _context = context;
             _contentStream = contentStream;
             GraphicsState = graphicsState;
 
@@ -35,14 +34,10 @@ private void _startPath()
                 .Write(new LineJoinOperator(GraphicsState.LineJoin))
                 .Write(new MiterLimitOperator(GraphicsState.MiterLimit))
                 .Write(new DashOperator(GraphicsState.Dash.Array, GraphicsState.Dash.Phase));
-
-            // write graphic state to stream
         }
 
         internal void FinishPath()
         {
-            // TODO: set colorspace for stroke and/or fill
-
             if (GraphicsState.Stroke is not null && GraphicsState.Fill is not null)
             {
                 if (GraphicsState.Stroke is GrayColor gs)
@@ -99,11 +94,9 @@ internal void FinishPath()
             _contentStream.RestoreState();
         }
 
-        public IShapeContext Close()
+        public void Close()
         {
             _contentStream.Write(new CloseOperator());
-
-            return _context;
         }
 
         public IPath CurveTo(double cpX1, double cpY1, double cpX2, double cpY2, double finalX, double finalY)
@@ -118,27 +111,27 @@ public IPath CurveTo(Point cp1, Point cp2, Point final)
             return this;
         }
 
-        public IPath CurveToWithEndAnker(double cpX, double cpY, double finalX, double finalY)
+        public IPath CurveToWithEndAnker(double cpX1, double cpY1, double finalX, double finalY)
         {
-            _contentStream.Write(new CubicBezierCurveFinalControlPointsOperator(cpX, cpY, finalX, finalY));
+            _contentStream.Write(new CubicBezierCurveFinalControlPointsOperator(cpX1, cpY1, finalX, finalY));
             return this;
         }
 
-        public IPath CurveToWithEndAnker(Point cp, Point final)
+        public IPath CurveToWithEndAnker(Point cp1, Point final)
         {
-            _contentStream.Write(new CubicBezierCurveFinalControlPointsOperator(cp, final));
+            _contentStream.Write(new CubicBezierCurveFinalControlPointsOperator(cp1, final));
             return this;
         }
 
-        public IPath CurveToWithStartAnker(double cpX, double cpY, double finalX, double finalY)
+        public IPath CurveToWithStartAnker(double cpX2, double cpY2, double finalX, double finalY)
         {
-            _contentStream.Write(new CubicBezierCurveInitialControlPointsOperator(cpX, cpY, finalX, finalY));
+            _contentStream.Write(new CubicBezierCurveInitialControlPointsOperator(cpX2, cpY2, finalX, finalY));
             return this;
         }
 
-        public IPath CurveToWithStartAnker(Point cp, Point final)
+        public IPath CurveToWithStartAnker(Point cp2, Point final)
         {
-            _contentStream.Write(new CubicBezierCurveInitialControlPointsOperator(cp, final));
+            _contentStream.Write(new CubicBezierCurveInitialControlPointsOperator(cp2, final));
             return this;
         }