1 /*
2 * Copyright (c) 2002-2025 Gargoyle Software Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 * https://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15 package org.htmlunit.platform.canvas.rendering;
16
17 import java.io.IOException;
18
19 import org.htmlunit.javascript.host.canvas.Path2D;
20
21 /**
22 * Interface to the rendering context used by
23 * {@link org.htmlunit.javascript.host.canvas.CanvasRenderingContext2D}.
24 *
25 * @author Ronald Brill
26 */
27 public interface RenderingBackend {
28
29 /**
30 * WindingRule to be used while rendering.
31 */
32 enum WindingRule {
33 /** WindingRule.NON_ZERO. */
34 NON_ZERO,
35 /** WindingRule.EVEN_ODD. */
36 EVEN_ODD
37 }
38
39 /**
40 * Starts a new path by emptying the list of sub-paths.
41 */
42 void beginPath();
43
44 /**
45 * Adds a cubic Bézier curve to the current sub-path. It requires
46 * three points: the first two are control points and the third one
47 * is the end point. The starting point is the latest point in the
48 * current path, which can be changed using moveTo() before
49 * creating the Bézier curve.
50 * @param cp1x the cp1x
51 * @param cp1y the cp1y
52 * @param cp2x the cp2x
53 * @param cp2y the cp2y
54 * @param x the x
55 * @param y the y
56 */
57 void bezierCurveTo(double cp1x, double cp1y, double cp2x, double cp2y,
58 double x, double y);
59
60 /**
61 * Adds a circular arc to the current sub-path.
62 * @param x the x
63 * @param y the y
64 * @param radius the radius
65 * @param startAngle the start angle
66 * @param endAngle the end angle
67 * @param anticlockwise is anti-clockwise
68 */
69 void arc(double x, double y, double radius, double startAngle,
70 double endAngle, boolean anticlockwise);
71
72 /**
73 * Paints the specified rectangular area.
74 * @param x the x
75 * @param y the y
76 * @param w the width
77 * @param h the height
78 */
79 void clearRect(double x, double y, double w, double h);
80
81 /**
82 * Draws images onto the context.
83 *
84 * @param imageData the reader to read the image from 8the first one)
85 * @param sx the X coordinate of the top left corner of the sub-rectangle of the source image
86 * to draw into the destination context
87 * @param sy the Y coordinate of the top left corner of the sub-rectangle of the source image
88 * to draw into the destination context
89 * @param sWidth the width of the sub-rectangle of the source image to draw into the destination context
90 * @param sHeight the height of the sub-rectangle of the source image to draw into the destination context
91 * @param dx the X coordinate in the destination canvas at which to place the top-left corner of the source image
92 * @param dy the Y coordinate in the destination canvas at which to place the top-left corner of the source image
93 * @param dWidth the width to draw the image in the destination canvas. This allows scaling of the drawn image
94 * @param dHeight the height to draw the image in the destination canvas. This allows scaling of the drawn image
95 * @throws IOException in case o problems
96 */
97 void drawImage(org.htmlunit.platform.image.ImageData imageData,
98 int sx, int sy, Integer sWidth, Integer sHeight,
99 int dx, int dy, Integer dWidth, Integer dHeight) throws IOException;
100
101 /**
102 * Constructs a base64 encoded string out of the image data.
103 *
104 * @param type the name of the image format
105 * @return the base64 encoded string
106 * @throws IOException in case o problems
107 */
108 String encodeToString(String type) throws IOException;
109
110 /**
111 * Creates an elliptical arc centered at (x, y) with the radii radiusX and radiusY.
112 * The path starts at startAngle and ends at endAngle, and travels in the direction
113 * given by anticlockwise (defaulting to clockwise).
114 * @param x the x
115 * @param y the y
116 * @param radiusX the radiusX
117 * @param radiusY the radiusY
118 * @param rotation the rotation
119 * @param startAngle the start angle
120 * @param endAngle the end angle
121 * @param anticlockwise is anti-clockwise
122 */
123 void ellipse(double x, double y,
124 double radiusX, double radiusY,
125 double rotation, double startAngle, double endAngle,
126 boolean anticlockwise);
127
128 /**
129 * Fills the current or given path with the current fillStyle.
130 */
131 void fill();
132
133 /**
134 * Paints the specified rectangular area.
135 * @param x the x
136 * @param y the y
137 * @param w the width
138 * @param h the height
139 */
140 void fillRect(int x, int y, int w, int h);
141
142 /**
143 * Fills a given text at the given (x, y) position.
144 * @param text the text
145 * @param x the x
146 * @param y the y
147 */
148 void fillText(String text, double x, double y);
149
150 /**
151 * Creates a byte array containing the (4) color values of all pixels.
152 *
153 * @param width the width
154 * @param height the height
155 * @param sx start point x
156 * @param sy start point y
157 * @return the bytes
158 */
159 byte[] getBytes(int width, int height, int sx, int sy);
160
161 /**
162 * Adds a straight line to the current sub-path by connecting the
163 * sub-path's last point to the specified (x, y) coordinates.
164 * @param x the x
165 * @param y the y
166 */
167 void lineTo(double x, double y);
168
169 /**
170 * Begins a new sub-path at the point specified
171 * by the given (x, y) coordinates.
172 * @param x the x
173 * @param y the y
174 */
175 void moveTo(double x, double y);
176
177 /**
178 * Paints data from the given ImageData object onto the canvas.
179 * @param imageDataBytes an array of pixel values
180 * @param imageDataHeight the height of the imageData
181 * @param imageDataWidth the width of the imageData
182 * @param dx horizontal position (x coordinate) at which to place the image data in the destination canvas
183 * @param dy vertical position (y coordinate) at which to place the image data in the destination canvas
184 * @param dirtyX horizontal position (x coordinate) of the top-left corner
185 * from which the image data will be extracted. Defaults to 0.
186 * @param dirtyY vertical position (y coordinate) of the top-left corner
187 * from which the image data will be extracted. Defaults to 0.
188 * @param dirtyWidth width of the rectangle to be painted.
189 * Defaults to the width of the image data.
190 * @param dirtyHeight height of the rectangle to be painted.
191 * Defaults to the height of the image data.
192 */
193 void putImageData(byte[] imageDataBytes, int imageDataHeight, int imageDataWidth,
194 int dx, int dy, int dirtyX, int dirtyY, int dirtyWidth, int dirtyHeight);
195
196 /**
197 * Adds a quadratic Bézier curve to the current sub-path. It requires
198 * two points: the first one is a control point and the second one is
199 * the end point. The starting point is the latest point in the
200 * current path, which can be changed using moveTo() before
201 * creating the quadratic Bézier curve.
202 * @param cpx the cpx
203 * @param cpy the cpy
204 * @param x the x
205 * @param y the y
206 */
207 void quadraticCurveTo(double cpx, double cpy, double x, double y);
208
209 /**
210 * Adds a rectangle to the current path.
211 * @param x the x
212 * @param y the y
213 * @param w the width
214 * @param h the height
215 */
216 void rect(double x, double y, double w, double h);
217
218 /**
219 * Restores the most recently saved canvas state by popping the top
220 * entry in the drawing state stack. If there is no saved state,
221 * this method does nothing.
222 */
223 void restore();
224
225 /**
226 * Adds a rotation to the transformation matrix.
227 * @param angle the angle
228 */
229 void rotate(double angle);
230
231 /**
232 * Saves the entire state of the canvas by pushing
233 * the current state onto a stack.
234 */
235 void save();
236
237 /**
238 * Sets the {@code fillStyle} property.
239 * @param fillStyle the {@code fillStyle} property
240 */
241 void setFillStyle(String fillStyle);
242
243 /**
244 * Sets the {@code strokeStyle} property.
245 * @param strokeStyle the {@code strokeStyle} property
246 */
247 void setStrokeStyle(String strokeStyle);
248
249 /**
250 * Returns the {@code lineWidth} property.
251 * @return the {@code lineWidth} property
252 */
253 int getLineWidth();
254
255 /**
256 * Sets the {@code lineWidth} property.
257 * @param lineWidth the {@code lineWidth} property
258 */
259 void setLineWidth(int lineWidth);
260
261 /**
262 * Resets (overrides) the current transformation to the identity matrix,
263 * and then invokes a transformation described by the arguments of this method.
264 * This lets you scale, rotate, translate (move), and skew the context.
265 * @param m11 Horizontal scaling. A value of 1 results in no scaling
266 * @param m12 Vertical skewing
267 * @param m21 Horizontal skewing
268 * @param m22 Vertical scaling. A value of 1 results in no scaling
269 * @param dx Horizontal translation (moving)
270 * @param dy Vertical translation (moving).
271 */
272 void setTransform(double m11, double m12, double m21, double m22, double dx, double dy);
273
274 /**
275 * Strokes (outlines) the current or given path with the current stroke style.
276 */
277 void stroke();
278
279 /**
280 * Paints the specified rectangular area.
281 * @param x the x
282 * @param y the y
283 * @param w the width
284 * @param h the height
285 */
286 void strokeRect(int x, int y, int w, int h);
287
288 /**
289 * Multiplies the current transformation with the matrix described by the
290 * arguments of this method. This lets you scale, rotate, translate (move),
291 * and skew the context.
292 * @param m11 Horizontal scaling. A value of 1 results in no scaling
293 * @param m12 Vertical skewing
294 * @param m21 Horizontal skewing
295 * @param m22 Vertical scaling. A value of 1 results in no scaling
296 * @param dx Horizontal translation (moving)
297 * @param dy Vertical translation (moving).
298 */
299 void transform(double m11, double m12, double m21, double m22, double dx, double dy);
300
301 /**
302 * Adds a translation transformation to the current matrix.
303 * @param x the x
304 * @param y the y
305 */
306 void translate(int x, int y);
307
308 /**
309 * Turns the current or given path into the current clipping region.
310 * It replaces any previous clipping region.
311 * @param windingRule the RenderingBackend.WindingRule {@link WindingRule}
312 * to be used
313 * @param path the path or null if the current path should be used
314 */
315 void clip(RenderingBackend.WindingRule windingRule, Path2D path);
316
317 /**
318 * Attempts to add a straight line from the current point to the start of the current sub-path.
319 * If the shape has already been closed or has only one point, this function does nothing.
320 */
321 void closePath();
322
323 /**
324 * @return the alpha (transparency) value that is applied to shapes and images
325 * before they are drawn onto the canvas.
326 */
327 double getGlobalAlpha();
328
329 /**
330 * Specifies the alpha (transparency) value that is applied to shapes and images
331 * before they are drawn onto the canvas.
332 * @param globalAlpha the new alpha
333 */
334 void setGlobalAlpha(double globalAlpha);
335 }