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