[[ ClipToPath ]] Implement clip to path

montegoulding · montegoulding · commit 0c073bf5252d · 2018-05-30T10:20:39.000+10:00
This patch implements a new statement in the lcb canvas library to clip
to a path. Previously only setting a clipping rectangle was supported
however this patch allows for more complext cliping paths. It additionally
simplifies the clipping of images as there is no need to create a pattern
paint from them and fill a path.
diff --git a/docs/lcb/notes/feature-cliptopath.md b/docs/lcb/notes/feature-cliptopath.md
@@ -0,0 +1,13 @@
+# LiveCode Builder Host Library
+## Canvas library
+
+A new statement `clip to <path> on <canvas>` has been implemented to allow drawing on a
+canvas to be clipped to the path. Previously the clip region could only be set to a
+rectangle via the `clip to <rectangle> on <canvas>` statement.
+
+For example to draw an image into a circle:
+
+    clip to circle path centered at point [my width /2,my height / 2] with radius my width/2 on this canvas
+    variable tImage as Image
+    put image from resource file "foo.png" into tImage
+    draw tImage into rectangle [0, 0, the width of tImage, the height of tImage] of this canvas
diff --git a/engine/src/canvas.lcb b/engine/src/canvas.lcb
@@ -4288,6 +4288,7 @@ public foreign handler MCCanvasFillPath(in pPath as Path, in pCanvas as Canvas)
 public foreign handler MCCanvasStroke(in pCanvas as Canvas) returns nothing binds to "<builtin>"
 public foreign handler MCCanvasStrokePath(in pPath as Path, in pCanvas as Canvas) returns nothing binds to "<builtin>"
 public foreign handler MCCanvasClipToRect(in pClip as Rectangle, in pCanvas as Canvas) returns nothing binds to "<builtin>"
+public foreign handler MCCanvasClipToPath(in pClip as Path, in pCanvas as Canvas) returns nothing binds to "<builtin>"
 public foreign handler MCCanvasAddPath(in pPath as Path, in pCanvas as Canvas) returns nothing binds to "<builtin>"
 public foreign handler MCCanvasDrawImage(in pImage as Image, in pDest as Rectangle, in pCanvas as Canvas) returns nothing binds to "<builtin>"
 public foreign handler MCCanvasDrawRectOfImage(in pSrc as Rectangle, in pImage as Image, in pDst as Rectangle, in pCanvas as Canvas) returns nothing binds to "<builtin>"
@@ -4612,6 +4613,31 @@ end syntax
 
 //////////
 
+/**
+Summary:    Clip to a path on a canvas.
+
+mCanvas:        An expression which evaluates to a canvas.
+mPath:    An expression which evaluates to a path.
+
+Description:    Modifies the clip of <mCanvas> by intersecting with <mRect>. Drawing operations on <mCanvas> will be confined to the clip region.
+
+Example:
+// Set the canvas clip
+clip to circle path centered at point [100,100] with radius 50 on this canvas
+
+// Fill rectangle path on canvas. only the region of the rectangle that falls within the canvas clip will be rendered.
+fill rectangle path of rectangle [25, 25, 75, 75] on this canvas
+
+Tags:    Canvas
+*/
+syntax CanvasOperationClipPath is statement
+    "clip" "to" <mPath: Expression> "on" <mCanvas: Expression>
+begin
+    MCCanvasClipToPath(mPath, mCanvas)
+end syntax
+
+//////////
+
 /**
 Summary:	Add a path to a canvas.
 
diff --git a/engine/src/module-canvas.cpp b/engine/src/module-canvas.cpp
@@ -5781,6 +5781,15 @@ void MCCanvasClipToRect(MCCanvasRectangleRef p_rect, MCCanvasRef p_canvas)
 	MCGContextClipToRect(t_canvas->context, *MCCanvasRectangleGet(p_rect));
 }
 
+MC_DLLEXPORT_DEF
+void MCCanvasClipToPath(MCCanvasPathRef p_path, MCCanvasRef p_canvas)
+{
+    __MCCanvasImpl *t_canvas;
+    t_canvas = MCCanvasGet(p_canvas);
+    
+    MCGContextClipToPath(t_canvas->context, *MCCanvasPathGet(p_path));
+}
+
 MC_DLLEXPORT_DEF
 void MCCanvasAddPath(MCCanvasPathRef p_path, MCCanvasRef p_canvas)
 {
diff --git a/engine/src/module-canvas.h b/engine/src/module-canvas.h
@@ -569,6 +569,7 @@ extern "C" MC_DLLEXPORT void MCCanvasFillPath(MCCanvasPathRef p_path, MCCanvasRe
 extern "C" MC_DLLEXPORT void MCCanvasStroke(MCCanvasRef p_canvas);
 extern "C" MC_DLLEXPORT void MCCanvasStrokePath(MCCanvasPathRef p_path, MCCanvasRef p_canvas);
 extern "C" MC_DLLEXPORT void MCCanvasClipToRect(MCCanvasRectangleRef p_rect, MCCanvasRef p_canvas);
+extern "C" MC_DLLEXPORT void MCCanvasClipToPath(MCCanvasPathRef p_path, MCCanvasRef p_canvas);
 extern "C" MC_DLLEXPORT void MCCanvasAddPath(MCCanvasPathRef p_path, MCCanvasRef p_canvas);
 extern "C" MC_DLLEXPORT void MCCanvasDrawImage(MCCanvasImageRef p_image, MCCanvasRectangleRef p_dst_rect, MCCanvasRef p_canvas);
 extern "C" MC_DLLEXPORT void MCCanvasDrawRectOfImage(MCCanvasRectangleRef p_src_rect, MCCanvasImageRef p_image, MCCanvasRectangleRef p_dst_rect, MCCanvasRef p_canvas);
diff --git a/libgraphics/include/graphics.h b/libgraphics/include/graphics.h
@@ -925,6 +925,7 @@ void MCGContextBeginWithEffects(MCGContextRef context, MCGRectangle shape, const
 void MCGContextEnd(MCGContextRef context);
 
 void MCGContextClipToRect(MCGContextRef context, MCGRectangle rect);
+void MCGContextClipToPath(MCGContextRef context, MCGPathRef path);
 void MCGContextSetClipToRect(MCGContextRef context, MCGRectangle rect);
 MCGRectangle MCGContextGetClipBounds(MCGContextRef context);
 MCGRectangle MCGContextGetDeviceClipBounds(MCGContextRef context);
diff --git a/libgraphics/src/context.cpp b/libgraphics/src/context.cpp
@@ -1340,6 +1340,14 @@ void MCGContextClipToRect(MCGContextRef self, MCGRectangle p_rect)
 	self -> layer -> canvas -> clipRect(MCGRectangleToSkRect(p_rect), SkRegion::kIntersect_Op, self -> state -> should_antialias);
 }
 
+void MCGContextClipToPath(MCGContextRef self, MCGPathRef p_path)
+{
+    if (!MCGContextIsValid(self) || !MCGPathIsValid(p_path))
+        return;
+    
+    self -> layer -> canvas -> clipPath(*p_path -> path, SkRegion::kIntersect_Op, self -> state -> should_antialias);
+}
+
 void MCGContextSetClipToDeviceRegion(MCGContextRef self, MCGRegionRef p_region)
 {
 	if (!MCGContextIsValid(self) || p_region == nil)

Original file line number	Diff line number	Diff line change
`@@ -1340,6 +1340,14 @@ void MCGContextClipToRect(MCGContextRef self, MCGRectangle p_rect)`
`1340`	`1340`	`self -> layer -> canvas -> clipRect(MCGRectangleToSkRect(p_rect), SkRegion::kIntersect_Op, self -> state -> should_antialias);`
`1341`	`1341`	`}`
`1342`	`1342`
	`1343`	`+void MCGContextClipToPath(MCGContextRef self, MCGPathRef p_path)`
	`1344`	`+{`
	`1345`	`+ if (!MCGContextIsValid(self) \|\| !MCGPathIsValid(p_path))`
	`1346`	`+ return;`
	`1347`	`+`
	`1348`	`+ self -> layer -> canvas -> clipPath(*p_path -> path, SkRegion::kIntersect_Op, self -> state -> should_antialias);`
	`1349`	`+}`
	`1350`	`+`
`1343`	`1351`	`void MCGContextSetClipToDeviceRegion(MCGContextRef self, MCGRegionRef p_region)`
`1344`	`1352`	`{`
`1345`	`1353`	`if (!MCGContextIsValid(self) \|\| p_region == nil)`