Merge pull request #1701 from syncfusion-content/261980-ug

261980-ug :Explained about set and restore clipping mechanism in PDF document

Author: Moorthy-K

Document-Processing/PDF/PDF-Library/NET/Working-with-Images.md

@@ -618,6 +618,136 @@ doc.Close(True)
 
 You can download a complete working sample from [GitHub](https://github.com/SyncfusionExamples/PDF-Examples/tree/master/Images/Paginate-an-image-in-PDF-document). 
 
+## Clipping and Graphics State
+
+This example demonstrates how to draw an image in a PDF document and apply a clipping region using the [SetClip](https://help.syncfusion.com/cr/document-processing/Syncfusion.Pdf.Graphics.PdfGraphics.html#methods) method. Clipping restricts drawing to a defined area, allowing partial rendering of content. The code also uses [Save](https://help.syncfusion.com/cr/document-processing/Syncfusion.Pdf.Graphics.PdfGraphics.html#methods) and [Restore](https://help.syncfusion.com/cr/document-processing/Syncfusion.Pdf.Graphics.PdfGraphics.html#methods) methods of [PdfGraphics](https://help.syncfusion.com/cr/document-processing/Syncfusion.Pdf.Graphics.PdfGraphics.html) to manage the graphics state, enabling temporary clipping and restoring the full drawing area afterward. 
+
+{% tabs %} 
+
+{% highlight c# tabtitle="C# [Cross-platform]" %} 
+
+using Syncfusion.Drawing;
+using Syncfusion.Pdf;
+using Syncfusion.Pdf.Graphics;
+
+// Create a new PDF document
+using (PdfDocument document = new PdfDocument())
+{
+    // Add a page to the document
+    PdfPage page = document.Pages.Add();
+    // Get the graphics object for the page
+    PdfGraphics graphics = page.Graphics;
+    // Open the image file as a stream
+    using FileStream imageStream = new FileStream(Path.GetFullPath("Input.png"), FileMode.Open, FileAccess.Read);
+    // Load the image from the stream
+    PdfBitmap image = new PdfBitmap(imageStream);
+
+    // Save the current graphics state (to restore later)
+    PdfGraphicsState state = graphics.Save();
+
+    // Define a rectangular clipping region
+    RectangleF clipRect = new RectangleF(50, 50, 200, 100);
+    graphics.SetClip(clipRect);
+
+    // Draw the image — only the part within the clipping region will be visible
+    graphics.DrawImage(image, new RectangleF(40, 60, 150, 80));
+
+    // Restore the graphics state to remove the clipping region
+    graphics.Restore(state);
+    // Draw the image again — this time the full image will be visible
+    graphics.DrawImage(image, new RectangleF(60, 160, 150, 80));
+
+    // Save the PDF document
+    document.Save("Output.pdf");
+}
+
+{% endhighlight %}
+
+{% highlight c# tabtitle="C# [Windows-specific]" %}
+
+using System.Drawing;
+using Syncfusion.Pdf;
+using Syncfusion.Pdf.Graphics;
+
+// Create a new PDF document
+using (PdfDocument document = new PdfDocument())
+{
+    // Add a page to the document
+    PdfPage page = document.Pages.Add();
+    // Get the graphics object for the page
+    PdfGraphics graphics = page.Graphics;
+    // Open the image file as a stream
+    using FileStream imageStream = new FileStream(Path.GetFullPath("Input.png"), FileMode.Open, FileAccess.Read);
+    // Load the image from the stream
+    PdfBitmap image = new PdfBitmap(imageStream);
+
+    // Save the current graphics state (to restore later)
+    PdfGraphicsState state = graphics.Save();
+
+    // Define a rectangular clipping region
+    RectangleF clipRect = new RectangleF(50, 50, 200, 100);
+    graphics.SetClip(clipRect);
+
+    // Draw the image — only the part within the clipping region will be visible
+    graphics.DrawImage(image, new RectangleF(40, 60, 150, 80));
+
+    // Restore the graphics state to remove the clipping region
+    graphics.Restore(state);
+    // Draw the image again — this time the full image will be visible
+    graphics.DrawImage(image, new RectangleF(60, 160, 150, 80));
+
+    // Save the PDF document
+    document.Save("Output.pdf");
+}
+
+{% endhighlight %}
+
+{% highlight vb.net tabtitle="VB.NET [Windows-specific]" %}
+
+Imports System.Drawing
+Imports Syncfusion.Pdf
+Imports Syncfusion.Pdf.Graphics
+
+' Create a new PDF document
+Using document As New PdfDocument()
+' Add a page to the document
+Dim page As PdfPage = document.Pages.Add()
+
+' Get the graphics object for the page
+Dim graphics As PdfGraphics = page.Graphics
+
+' Open the image file as a stream
+Using imageStream As New FileStream(Path.GetFullPath("Input.png"), FileMode.Open, FileAccess.Read)
+' Load the image from the stream
+Dim image As New PdfBitmap(imageStream)
+
+' Save the current graphics state (to restore later)
+Dim state As PdfGraphicsState = graphics.Save()
+
+' Define a rectangular clipping region
+Dim clipRect As New RectangleF(50, 50, 200, 100)
+graphics.SetClip(clipRect)
+
+' Draw the image — only the part within the clipping region will be visible
+graphics.DrawImage(image, New RectangleF(40, 60, 150, 80))
+
+' Restore the graphics state to remove the clipping region
+graphics.Restore(state)
+
+' Draw the image again — this time the full image will be visible
+graphics.DrawImage(image, New RectangleF(60, 160, 150, 80))
+End Using
+
+' Save the PDF document
+document.Save("Output.pdf")
+End Using
+
+{% endhighlight %}
+
+{% endtabs %}  
+
+You can download a complete working sample from GitHub.
+
 ## Applying transparency and rotation to the image
 
 You can add transparency and rotation to the image using [SetTransparency](https://help.syncfusion.com/cr/document-processing/Syncfusion.Pdf.Graphics.PdfGraphics.html#Syncfusion_Pdf_Graphics_PdfGraphics_SetTransparency_System_Single_) and [RotateTransform](https://help.syncfusion.com/cr/document-processing/Syncfusion.Pdf.Graphics.PdfGraphics.html#Syncfusion_Pdf_Graphics_PdfGraphics_RotateTransform_System_Single_) methods of [PdfGraphics](https://help.syncfusion.com/cr/document-processing/Syncfusion.Pdf.Graphics.PdfGraphics.html) respectively. This is explained in the below code snippet.