1 /*
2 * Copyright (c) 2002-2026 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 * LineJoin to be used while rendering.
41 */
42 enum LineJoin {
43 /** LineJoin.MITER. */
44 MITER,
45 /** LineJoin.ROUND. */
46 ROUND,
47 /** LineJoin.BEVEL. */
48 BEVEL
49 }
50
51 /**
52 * LineCap to be used while rendering.
53 */
54 enum LineCap {
55 /** LineCap.BUTT. */
56 BUTT,
57 /** LineCap.ROUND. */
58 ROUND,
59 /** LineCap.SQUARE. */
60 SQUARE
61 }
62
63 /**
64 * Starts a new path by emptying the list of sub-paths.
65 */
66 void beginPath();
67
68 /**
69 * Adds a cubic Bézier curve to the current sub-path. It requires
70 * three points: the first two are control points and the third one
71 * is the end point. The starting point is the latest point in the
72 * current path, which can be changed using moveTo() before
73 * creating the Bézier curve.
74 * @param cp1x the cp1x
75 * @param cp1y the cp1y
76 * @param cp2x the cp2x
77 * @param cp2y the cp2y
78 * @param x the x
79 * @param y the y
80 */
81 void bezierCurveTo(double cp1x, double cp1y, double cp2x, double cp2y,
82 double x, double y);
83
84 /**
85 * Adds a circular arc to the current sub-path.
86 * @param x the x
87 * @param y the y
88 * @param radius the radius
89 * @param startAngle the start angle
90 * @param endAngle the end angle
91 * @param anticlockwise is anti-clockwise
92 */
93 void arc(double x, double y, double radius, double startAngle,
94 double endAngle, boolean anticlockwise);
95
96 /**
97 * Paints the specified rectangular area.
98 * @param x the x
99 * @param y the y
100 * @param w the width
101 * @param h the height
102 */
103 void clearRect(double x, double y, double w, double h);
104
105 /**
106 * Draws images onto the context.
107 *
108 * @param imageData the reader to read the image from 8the first one)
109 * @param sx the X coordinate of the top left corner of the sub-rectangle of the source image
110 * to draw into the destination context
111 * @param sy the Y coordinate of the top left corner of the sub-rectangle of the source image
112 * to draw into the destination context
113 * @param sWidth the width of the sub-rectangle of the source image to draw into the destination context
114 * @param sHeight the height of the sub-rectangle of the source image to draw into the destination context
115 * @param dx the X coordinate in the destination canvas at which to place the top-left corner of the source image
116 * @param dy the Y coordinate in the destination canvas at which to place the top-left corner of the source image
117 * @param dWidth the width to draw the image in the destination canvas. This allows scaling of the drawn image
118 * @param dHeight the height to draw the image in the destination canvas. This allows scaling of the drawn image
119 * @throws IOException in case o problems
120 */
121 void drawImage(org.htmlunit.platform.image.ImageData imageData,
122 int sx, int sy, Integer sWidth, Integer sHeight,
123 int dx, int dy, Integer dWidth, Integer dHeight) throws IOException;
124
125 /**
126 * Constructs a base64 encoded string out of the image data.
127 *
128 * @param type the name of the image format
129 * @return the base64 encoded string
130 * @throws IOException in case o problems
131 */
132 String encodeToString(String type) throws IOException;
133
134 /**
135 * Creates an elliptical arc centered at (x, y) with the radii radiusX and radiusY.
136 * The path starts at startAngle and ends at endAngle, and travels in the direction
137 * given by anticlockwise (defaulting to clockwise).
138 * @param x the x
139 * @param y the y
140 * @param radiusX the radiusX
141 * @param radiusY the radiusY
142 * @param rotation the rotation
143 * @param startAngle the start angle
144 * @param endAngle the end angle
145 * @param anticlockwise is anti-clockwise
146 */
147 void ellipse(double x, double y,
148 double radiusX, double radiusY,
149 double rotation, double startAngle, double endAngle,
150 boolean anticlockwise);
151
152 /**
153 * Fills the current or given path with the current fillStyle.
154 * @param windingRule the {@link WindingRule}
155 */
156 void fill(RenderingBackend.WindingRule windingRule);
157
158 /**
159 * Paints the specified rectangular area.
160 * @param x the x
161 * @param y the y
162 * @param w the width
163 * @param h the height
164 */
165 void fillRect(double x, double y, double w, double h);
166
167 /**
168 * Fills a given text at the given (x, y) position.
169 * @param text the text
170 * @param x the x
171 * @param y the y
172 */
173 void fillText(String text, double x, double y);
174
175 /**
176 * Creates a byte array containing the (4) color values of all pixels.
177 *
178 * @param width the width
179 * @param height the height
180 * @param sx start point x
181 * @param sy start point y
182 * @return the bytes
183 */
184 byte[] getBytes(int width, int height, int sx, int sy);
185
186 /**
187 * Adds a straight line to the current sub-path by connecting the
188 * sub-path's last point to the specified (x, y) coordinates.
189 * @param x the x
190 * @param y the y
191 */
192 void lineTo(double x, double y);
193
194 /**
195 * Begins a new sub-path at the point specified
196 * by the given (x, y) coordinates.
197 * @param x the x
198 * @param y the y
199 */
200 void moveTo(double x, double y);
201
202 /**
203 * Paints data from the given ImageData object onto the canvas.
204 * @param imageDataBytes an array of pixel values
205 * @param imageDataWidth the width of the imageData
206 * @param imageDataHeight the height of the imageData
207 * @param dx horizontal position (x coordinate) at which to place the image data in the destination canvas
208 * @param dy vertical position (y coordinate) at which to place the image data in the destination canvas
209 * @param dirtyX horizontal position (x coordinate) of the top-left corner
210 * from which the image data will be extracted. Defaults to 0.
211 * @param dirtyY vertical position (y coordinate) of the top-left corner
212 * from which the image data will be extracted. Defaults to 0.
213 * @param dirtyWidth width of the rectangle to be painted.
214 * Defaults to the width of the image data.
215 * @param dirtyHeight height of the rectangle to be painted.
216 * Defaults to the height of the image data.
217 */
218 void putImageData(byte[] imageDataBytes, int imageDataWidth, int imageDataHeight,
219 int dx, int dy, int dirtyX, int dirtyY, int dirtyWidth, int dirtyHeight);
220
221 /**
222 * Adds a quadratic Bézier curve to the current sub-path. It requires
223 * two points: the first one is a control point and the second one is
224 * the end point. The starting point is the latest point in the
225 * current path, which can be changed using moveTo() before
226 * creating the quadratic Bézier curve.
227 * @param cpx the cpx
228 * @param cpy the cpy
229 * @param x the x
230 * @param y the y
231 */
232 void quadraticCurveTo(double cpx, double cpy, double x, double y);
233
234 /**
235 * Adds a rectangle to the current path.
236 * @param x the x
237 * @param y the y
238 * @param w the width
239 * @param h the height
240 */
241 void rect(double x, double y, double w, double h);
242
243 /**
244 * Restores the most recently saved canvas state by popping the top
245 * entry in the drawing state stack. If there is no saved state,
246 * this method does nothing.
247 */
248 void restore();
249
250 /**
251 * Adds a rotation to the transformation matrix.
252 * @param angle the angle
253 */
254 void rotate(double angle);
255
256 /**
257 * Saves the entire state of the canvas by pushing
258 * the current state onto a stack.
259 */
260 void save();
261
262 /**
263 * Sets the {@code fillStyle} property.
264 * @param fillStyle the {@code fillStyle} property
265 */
266 void setFillStyle(String fillStyle);
267
268 /**
269 * Sets the {@code strokeStyle} property.
270 * @param strokeStyle the {@code strokeStyle} property
271 */
272 void setStrokeStyle(String strokeStyle);
273
274 /**
275 * Returns the {@code lineWidth} property.
276 * @return the {@code lineWidth} property
277 */
278 float getLineWidth();
279
280 /**
281 * Sets the {@code lineWidth} property.
282 * @param lineWidth the {@code lineWidth} property
283 */
284 void setLineWidth(float lineWidth);
285
286 /**
287 * Resets (overrides) the current transformation to the identity matrix,
288 * and then invokes a transformation described by the arguments of this method.
289 * This lets you scale, rotate, translate (move), and skew the context.
290 * @param m11 Horizontal scaling. A value of 1 results in no scaling
291 * @param m12 Vertical skewing
292 * @param m21 Horizontal skewing
293 * @param m22 Vertical scaling. A value of 1 results in no scaling
294 * @param dx Horizontal translation (moving)
295 * @param dy Vertical translation (moving).
296 */
297 void setTransform(double m11, double m12, double m21, double m22, double dx, double dy);
298
299 /**
300 * Strokes (outlines) the current or given path with the current stroke style.
301 */
302 void stroke();
303
304 /**
305 * Paints the specified rectangular area.
306 * @param x the x
307 * @param y the y
308 * @param w the width
309 * @param h the height
310 */
311 void strokeRect(double x, double y, double w, double h);
312
313 /**
314 * Multiplies the current transformation with the matrix described by the
315 * arguments of this method. This lets you scale, rotate, translate (move),
316 * and skew the context.
317 * @param m11 Horizontal scaling. A value of 1 results in no scaling
318 * @param m12 Vertical skewing
319 * @param m21 Horizontal skewing
320 * @param m22 Vertical scaling. A value of 1 results in no scaling
321 * @param dx Horizontal translation (moving)
322 * @param dy Vertical translation (moving).
323 */
324 void transform(double m11, double m12, double m21, double m22, double dx, double dy);
325
326 /**
327 * Adds a translation transformation to the current matrix.
328 * @param x the x
329 * @param y the y
330 */
331 void translate(double x, double y);
332
333 /**
334 * Turns the current or given path into the current clipping region.
335 * It replaces any previous clipping region.
336 * @param windingRule the RenderingBackend.WindingRule {@link WindingRule}
337 * to be used
338 * @param path the path or null if the current path should be used
339 */
340 void clip(RenderingBackend.WindingRule windingRule, Path2D path);
341
342 /**
343 * Attempts to add a straight line from the current point to the start of the current sub-path.
344 * If the shape has already been closed or has only one point, this function does nothing.
345 */
346 void closePath();
347
348 /**
349 * Returns the alpha (transparency) value that is applied to shapes and images
350 * before they are drawn onto the canvas.
351 *
352 * @return the alpha (transparency) value that is applied to shapes and images
353 * before they are drawn onto the canvas.
354 */
355 double getGlobalAlpha();
356
357 /**
358 * Specifies the alpha (transparency) value that is applied to shapes and images
359 * before they are drawn onto the canvas.
360 * @param globalAlpha the new alpha
361 */
362 void setGlobalAlpha(double globalAlpha);
363
364 /**
365 * Returns the the shape used to join two line segments where they meet.
366 * There are three possible values for this property: "round", "bevel",
367 * and "miter". The default is "miter".
368 *
369 * @return the the shape used to join two line segments
370 */
371 LineJoin getLineJoin();
372
373 /**
374 * Sets the {@code lineJoin} property.
375 * @param lineJoin the {@code lineJoin} property value
376 */
377 void setLineJoin(LineJoin lineJoin);
378
379 /**
380 * Returns the shape used to draw the end points of lines.
381 *
382 * @return the shape used to draw the end points of lines.
383 */
384 LineCap getLineCap();
385
386 /**
387 * Sets the {@code lineCap} property.
388 * @param lineCap the {@code lineCap} property value
389 */
390 void setLineCap(LineCap lineCap);
391 }