Documentation: Image

Source/QuestPDF/Elements/DynamicImage.cs

@@ -7,6 +7,11 @@ using SkiaSharp;
 
 namespace QuestPDF.Elements
 {
+    /// <summary>
+    /// Generates an image based on the given resolution.
+    /// </summary>
+    /// <param name="size">Desired resolution of the image in pixels.</param>
+    /// <returns>An image in PNG, JPEG, or WEBP image format returned as byte array.</returns>
     public delegate byte[] GenerateDynamicImageDelegate(ImageSize size);
     
     internal class DynamicImage : Element

Source/QuestPDF/Fluent/ImageExtensions.cs

@@ -7,6 +7,37 @@ using SkiaSharp;
 
 namespace QuestPDF.Fluent
 {
+    public class DynamicImageDescriptor
+    {
+        private Elements.DynamicImage ImageElement { get; }
+        
+        internal DynamicImageDescriptor(Elements.DynamicImage imageElement)
+        {
+            ImageElement = imageElement;
+        }
+        
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.useOriginalImage"]/*' />
+        public DynamicImageDescriptor UseOriginalImage(bool value = true)
+        {
+            ImageElement.UseOriginalImage = value;
+            return this;
+        }
+        
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.rasterDPI"]/*' />
+        public DynamicImageDescriptor WithRasterDpi(int dpi)
+        {
+            ImageElement.TargetDpi = dpi;
+            return this;
+        }
+
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.compressionQuality"]/*' />
+        public DynamicImageDescriptor WithCompressionQuality(ImageCompressionQuality quality)
+        {
+            ImageElement.CompressionQuality = quality;
+            return this;
+        }
+    }
+    
     public class ImageDescriptor
     {
         private Elements.Image ImageElement { get; }
@@ -22,33 +53,21 @@ namespace QuestPDF.Fluent
             ImageAspectRatio = imageSize.Width / (float)imageSize.Height;
         }
         
-        /// <summary>
-        /// When enabled, the library will not attempt to resize the image to fit the target DPI, nor save it with target image quality.
-        /// </summary>
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.useOriginalImage"]/*' />
         public ImageDescriptor UseOriginalImage(bool value = true)
         {
             ImageElement.UseOriginalImage = value;
             return this;
         }
         
-        /// <summary>
-        /// The DPI (pixels-per-inch) at which images and features without native PDF support will be rasterized.
-        /// A larger DPI would create a PDF that reflects the original intent with better fidelity, but it can make for larger PDF files too, which would use more memory while rendering, and it would be slower to be processed or sent online or to printer.
-        /// When generating images, this parameter also controls the resolution of the generated content.
-        /// Default value is 144.
-        /// </summary>
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.rasterDPI"]/*' />
         public ImageDescriptor WithRasterDpi(int dpi)
         {
             ImageElement.TargetDpi = dpi;
             return this;
         }
 
-        /// <summary>
-        /// Encoding quality controls the trade-off between size and quality.
-        /// When the image is opaque, it will be encoded using the JPEG format with the selected quality setting.
-        /// When the image contains an alpha channel, it is always encoded using the PNG format and this option is ignored.
-        /// The default value is "very high quality".
-        /// </summary>
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.compressionQuality"]/*' />
         public ImageDescriptor WithCompressionQuality(ImageCompressionQuality quality)
         {
             ImageElement.CompressionQuality = quality;
@@ -58,7 +77,7 @@ namespace QuestPDF.Fluent
         #region Aspect Ratio
         
         /// <summary>
-        /// The image scales to take the entire available width. Default.
+        /// Scales the image to fill the full width of its container. This is the default behavior.
         /// </summary>
         public ImageDescriptor FitWidth()
         {
@@ -66,7 +85,8 @@ namespace QuestPDF.Fluent
         }
         
         /// <summary>
-        /// The images scales to take the entire available height. Good in conjunction with constraining elements.
+        /// <para>The image stretches vertically to fit the full available height.</para>
+        /// <para>Often used with height-constraining elements such as: <see cref="ConstrainedExtensions.Height">Height</see>, <see cref="ConstrainedExtensions.MaxHeight">MaxHeight</see>, etc.</para>
         /// </summary>
         public ImageDescriptor FitHeight()
         {
@@ -74,20 +94,21 @@ namespace QuestPDF.Fluent
         }
         
         /// <summary>
-        /// This is the combination of both of the FitWidth and the FitHeight options. 
-        /// The element scales to occupy the entire available area while preserving its aspect ratio.
-        /// This means that sometimes it occupies the entire width and sometimes the entire height.
-        /// This is the safest option.
+        /// Combines the FitWidth and FitHeight settings.
+        /// The image resizes itself to utilize all available space, preserving its aspect ratio.
+        /// It will either fill the width or height based on the container's dimensions.
         /// </summary>
+        /// <remarks>
+        /// An optimal and safe choice.
+        /// </remarks>
         public ImageDescriptor FitArea()
         {
             return SetAspectRatio(AspectRatioOption.FitArea);
         }
         
         /// <summary>
-        /// The image resizes itself to occupy the entire available space.
-        /// It does not preserve proportions.
-        /// The image may look incorrectly scaled, and is not desired in most of the cases.
+        /// The image adjusts to fill all the available space, disregarding its original proportions.
+        /// This can lead to distorted scaling and is generally not recommended for most scenarios.
         /// </summary>
         public ImageDescriptor FitUnproportionally()
         {
@@ -107,24 +128,49 @@ namespace QuestPDF.Fluent
     
     public static class ImageExtensions
     {
+        /// <summary>
+        /// Draws an image by decoding it from a provided byte array.
+        /// <a href="https://www.questpdf.com/api-reference/image.html">Learn more</a>
+        /// </summary>
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.remarks"]/*' />
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.descriptor"]/*' />
         public static ImageDescriptor Image(this IContainer parent, byte[] imageData)
         {
             var image = Infrastructure.Image.FromBinaryData(imageData);
             return parent.Image(image);
         }
         
+        /// <summary>
+        /// Draws the image loaded from a file located at the provided path.
+        /// <a href="https://www.questpdf.com/api-reference/image.html">Learn more</a>
+        /// </summary>
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.remarks"]/*' />
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.descriptor"]/*' />
         public static ImageDescriptor Image(this IContainer parent, string filePath)
         {
             var image = Infrastructure.Image.FromFile(filePath);
             return parent.Image(image);
         }
         
+        /// <summary>
+        /// Draws the image loaded from a stream.
+        /// <a href="https://www.questpdf.com/api-reference/image.html">Learn more</a>
+        /// </summary>
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.remarks"]/*' />
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.descriptor"]/*' />
         public static ImageDescriptor Image(this IContainer parent, Stream fileStream)
         {
             var image = Infrastructure.Image.FromStream(fileStream);
             return parent.Image(image);
         }
         
+        /// <summary>
+        /// Draws the <see cref="Infrastructure.Image" /> object. Allows to optimize the generation process.
+        /// <br />
+        /// <a href="https://www.questpdf.com/api-reference/image.html">Learn more</a>
+        /// </summary>
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.remarks"]/*' />
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.descriptor"]/*' />
         public static ImageDescriptor Image(this IContainer parent, Infrastructure.Image image)
         {
             if (image == null)
@@ -143,13 +189,26 @@ namespace QuestPDF.Fluent
             parent.Element(aspectRationElement);
             return new ImageDescriptor(imageElement, aspectRationElement).FitWidth();
         }
-
-        public static void Image(this IContainer element, GenerateDynamicImageDelegate dynamicImageSource)
+        
+        /// <summary>
+        /// Renders an image of dynamic size dictated by the document layout constraints.
+        /// </summary>
+        /// <remarks>
+        /// Ideal for generating pixel-perfect images that might lose quality upon scaling, such as maps or charts.
+        /// </remarks>
+        /// <param name="dynamicImageSource">
+        /// A delegate that requests an image of desired resolution calculated based on target physical image size and provided DPI.
+        /// </param>
+        /// <returns>A descriptor for adjusting image attributes like scaling behavior, compression quality, and resolution.</returns>
+        public static DynamicImageDescriptor Image(this IContainer element, GenerateDynamicImageDelegate dynamicImageSource)
         {
-            element.Element(new DynamicImage
+            var dynamicImage = new DynamicImage
             {
                 Source = dynamicImageSource
-            });
+            };
+            
+            element.Element(dynamicImage);
+            return new DynamicImageDescriptor(dynamicImage);
         }
         
         #region Obsolete

Source/QuestPDF/Infrastructure/Image.cs

@@ -14,6 +14,15 @@ namespace QuestPDF.Infrastructure
         internal ImageCompressionQuality CompressionQuality { get; set; }
     }
     
+    /// <summary>
+    /// <para>Caches the image in local memory for efficient reuse.</para>
+    /// <para>Optimizes the generation process, especially:</para>
+    /// <para>- For images repeated in a single document to enhance performance and reduce output file size (e.g., an image used as list bullet icon).</para>
+    /// <para>- When an image appears on multiple document types for increased generation performance (e.g., a company logo).</para>
+    /// </summary>
+    /// <remarks>
+    /// This class is thread safe.
+    /// </remarks>
     public class Image
     {
         internal SKImage SkImage { get; }
@@ -61,6 +70,11 @@ namespace QuestPDF.Infrastructure
             return new Image(image);
         }
 
+        /// <summary>
+        /// Loads the image from binary data.
+        /// <a href="https://www.questpdf.com/api-reference/image.html">Learn more</a>
+        /// </summary>
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.remarks"]/*' />
         public static Image FromBinaryData(byte[] imageData)
         {
             var image = SKImage.FromEncodedData(imageData);
@@ -71,6 +85,11 @@ namespace QuestPDF.Infrastructure
             return new Image(image);
         }
 
+        /// <summary>
+        /// Loads the image from a file with specified path.
+        /// <a href="https://www.questpdf.com/api-reference/image.html">Learn more</a>
+        /// </summary>
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.remarks"]/*' />
         public static Image FromFile(string filePath)
         {
             var image = SKImage.FromEncodedData(filePath);
@@ -85,6 +104,11 @@ namespace QuestPDF.Infrastructure
             return new Image(image);
         }
 
+        /// <summary>
+        /// Loads the image from a stream.
+        /// <a href="https://www.questpdf.com/api-reference/image.html">Learn more</a>
+        /// </summary>
+        /// <include file='../Resources/Documentation.xml' path='documentation/doc[@for="image.remarks"]/*' />
         public static Image FromStream(Stream fileStream)
         {
             var image = SKImage.FromEncodedData(fileStream);

Source/QuestPDF/Infrastructure/ImageCompressionQuality.cs

@@ -3,32 +3,32 @@
     public enum ImageCompressionQuality
     {
         /// <summary>
-        /// JPEG format with compression set to 100 out of 100
+        /// JPEG format with target quality set to 100 out of 100
         /// </summary>
         Best,
 
         /// <summary>
-        /// JPEG format with compression set to 90 out of 100
+        /// JPEG format with target quality set to 90 out of 100
         /// </summary>
         VeryHigh,
 
         /// <summary>
-        /// JPEG format with compression set to 75 out of 100
+        /// JPEG format with target quality set to 75 out of 100
         /// </summary>
         High,
 
         /// <summary>
-        /// JPEG format with compression set to 50 out of 100
+        /// JPEG format with target quality set to 50 out of 100
         /// </summary>
         Medium,
 
         /// <summary>
-        /// JPEG format with compression set to 25 out of 100
+        /// JPEG format with target quality set to 25 out of 100
         /// </summary>
         Low,
 
         /// <summary>
-        /// JPEG format with compression set to 10 out of 100
+        /// JPEG format with target quality set to 10 out of 100
         /// </summary>
         VeryLow
     }

Source/QuestPDF/Infrastructure/ImageGenerationSettings.cs

@@ -17,8 +17,12 @@ namespace QuestPDF.Infrastructure
 
         /// <summary>
         /// The DPI (pixels-per-inch) at which the document will be rasterized. This parameter controls the resolution of produced images.
+        /// Higher DPI results in superior image quality but may increase the output file size.
         /// Default value is 288.
         /// </summary>
+        /// <example>
+        /// Consider a document of dimensions 3x4 inches. Using a DPI value of 300, the final image resolution translates to 900x1200 pixels.
+        /// </example>
         public int RasterDpi { get; set; } = DocumentSettings.DefaultRasterDpi * 4;