View Javadoc
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 }