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.javascript.host.dom;
16  
17  import org.htmlunit.corejs.javascript.Context;
18  import org.htmlunit.corejs.javascript.Function;
19  import org.htmlunit.corejs.javascript.Scriptable;
20  import org.htmlunit.corejs.javascript.VarScope;
21  import org.htmlunit.corejs.javascript.typedarrays.NativeFloat32Array;
22  import org.htmlunit.corejs.javascript.typedarrays.NativeFloat64Array;
23  import org.htmlunit.javascript.configuration.JsxClass;
24  import org.htmlunit.javascript.configuration.JsxConstructor;
25  import org.htmlunit.javascript.configuration.JsxConstructorAlias;
26  import org.htmlunit.javascript.configuration.JsxFunction;
27  import org.htmlunit.javascript.configuration.JsxGetter;
28  import org.htmlunit.javascript.configuration.JsxSetter;
29  import org.htmlunit.javascript.configuration.JsxStaticFunction;
30  
31  /**
32   * A JavaScript object for {@code DOMMatrix}.
33   *
34   * @author Ahmed Ashour
35   * @author Ronald Brill
36   *
37   * @see <a href="https://developer.mozilla.org/en-US/docs/Web/API/DOMMatrix">MDN Documentation</a>
38   */
39  @JsxClass
40  public class DOMMatrix extends DOMMatrixReadOnly {
41  
42      /**
43       * JavaScript constructor.
44       * @param cx the current context
45       * @param scope the scope
46       * @param args the arguments to the WebSocket constructor
47       * @param ctorObj the function object
48       * @param inNewExpr Is new or not
49       * @return the java object to allow JavaScript to access
50       */
51      @JsxConstructor
52      @JsxConstructorAlias(alias = "WebKitCSSMatrix")
53      public static DOMMatrix jsConstructor(final Context cx, final VarScope scope,
54              final Object[] args, final Function ctorObj, final boolean inNewExpr) {
55  
56          final DOMMatrix matrix = new DOMMatrix();
57          matrix.init(args, scope, ctorObj);
58          return matrix;
59      }
60  
61      /**
62       * {@inheritDoc}
63       */
64      @Override
65      @JsxGetter
66      public double getM11() {
67          return super.getM11();
68      }
69  
70      /**
71       * {@inheritDoc}
72       */
73      @Override
74      @JsxSetter
75      public void setM11(final double m11) {
76          super.setM11(m11);
77      }
78  
79      /**
80       * {@inheritDoc}
81       */
82      @Override
83      @JsxGetter
84      public double getM12() {
85          return super.getM12();
86      }
87  
88      /**
89       * {@inheritDoc}
90       */
91      @Override
92      @JsxSetter
93      public void setM12(final double m12) {
94          super.setM12(m12);
95      }
96  
97      /**
98       * {@inheritDoc}
99       */
100     @Override
101     @JsxGetter
102     public double getM13() {
103         return super.getM13();
104     }
105 
106     /**
107      * {@inheritDoc}
108      */
109     @Override
110     @JsxSetter
111     public void setM13(final double m13) {
112         super.setM13(m13);
113         if (m13 != 0) {
114             setIs2D(false);
115         }
116     }
117 
118     /**
119      * {@inheritDoc}
120      */
121     @Override
122     @JsxGetter
123     public double getM14() {
124         return super.getM14();
125     }
126 
127     /**
128      * {@inheritDoc}
129      */
130     @Override
131     @JsxSetter
132     public void setM14(final double m14) {
133         super.setM14(m14);
134         if (m14 != 0) {
135             setIs2D(false);
136         }
137     }
138 
139     /**
140      * {@inheritDoc}
141      */
142     @Override
143     @JsxGetter
144     public double getM21() {
145         return super.getM21();
146     }
147 
148     /**
149      * {@inheritDoc}
150      */
151     @Override
152     @JsxSetter
153     public void setM21(final double m21) {
154         super.setM21(m21);
155     }
156 
157     /**
158      * {@inheritDoc}
159      */
160     @Override
161     @JsxGetter
162     public double getM22() {
163         return super.getM22();
164     }
165 
166     /**
167      * {@inheritDoc}
168      */
169     @Override
170     @JsxSetter
171     public void setM22(final double m22) {
172         super.setM22(m22);
173     }
174 
175     /**
176      * {@inheritDoc}
177      */
178     @Override
179     @JsxGetter
180     public double getM23() {
181         return super.getM23();
182     }
183 
184     /**
185      * {@inheritDoc}
186      */
187     @Override
188     @JsxSetter
189     public void setM23(final double m23) {
190         super.setM23(m23);
191         if (m23 != 0) {
192             setIs2D(false);
193         }
194     }
195 
196     /**
197      * {@inheritDoc}
198      */
199     @Override
200     @JsxGetter
201     public double getM24() {
202         return super.getM24();
203     }
204 
205     /**
206      * {@inheritDoc}
207      */
208     @Override
209     @JsxSetter
210     public void setM24(final double m24) {
211         super.setM24(m24);
212         if (m24 != 0) {
213             setIs2D(false);
214         }
215     }
216 
217     /**
218      * {@inheritDoc}
219      */
220     @Override
221     @JsxGetter
222     public double getM31() {
223         return super.getM31();
224     }
225 
226     /**
227      * {@inheritDoc}
228      */
229     @Override
230     @JsxSetter
231     public void setM31(final double m31) {
232         super.setM31(m31);
233         if (m31 != 0) {
234             setIs2D(false);
235         }
236     }
237 
238     /**
239      * {@inheritDoc}
240      */
241     @Override
242     @JsxGetter
243     public double getM32() {
244         return super.getM32();
245     }
246 
247     /**
248      * {@inheritDoc}
249      */
250     @Override
251     @JsxSetter
252     public void setM32(final double m32) {
253         super.setM32(m32);
254         if (m32 != 0) {
255             setIs2D(false);
256         }
257     }
258 
259     /**
260      * {@inheritDoc}
261      */
262     @Override
263     @JsxGetter
264     public double getM33() {
265         return super.getM33();
266     }
267 
268     /**
269      * {@inheritDoc}
270      */
271     @Override
272     @JsxSetter
273     public void setM33(final double m33) {
274         super.setM33(m33);
275         if (m33 != 1) {
276             setIs2D(false);
277         }
278     }
279 
280     /**
281      * {@inheritDoc}
282      */
283     @Override
284     @JsxGetter
285     public double getM34() {
286         return super.getM34();
287     }
288 
289     /**
290      * {@inheritDoc}
291      */
292     @Override
293     @JsxSetter
294     public void setM34(final double m34) {
295         super.setM34(m34);
296         if (m34 != 0) {
297             setIs2D(false);
298         }
299     }
300 
301     /**
302      * {@inheritDoc}
303      */
304     @Override
305     @JsxGetter
306     public double getM41() {
307         return super.getM41();
308     }
309 
310     /**
311      * {@inheritDoc}
312      */
313     @Override
314     @JsxSetter
315     public void setM41(final double m41) {
316         super.setM41(m41);
317     }
318 
319     /**
320      * {@inheritDoc}
321      */
322     @Override
323     @JsxGetter
324     public double getM42() {
325         return super.getM42();
326     }
327 
328     /**
329      * {@inheritDoc}
330      */
331     @Override
332     @JsxSetter
333     public void setM42(final double m42) {
334         super.setM42(m42);
335     }
336 
337     /**
338      * {@inheritDoc}
339      */
340     @Override
341     @JsxGetter
342     public double getM43() {
343         return super.getM43();
344     }
345 
346     /**
347      * {@inheritDoc}
348      */
349     @Override
350     @JsxSetter
351     public void setM43(final double m43) {
352         super.setM43(m43);
353         if (m43 != 0) {
354             setIs2D(false);
355         }
356     }
357 
358     /**
359      * {@inheritDoc}
360      */
361     @Override
362     @JsxGetter
363     public double getM44() {
364         return super.getM44();
365     }
366 
367     /**
368      * {@inheritDoc}
369      */
370     @Override
371     @JsxSetter
372     public void setM44(final double m44) {
373         super.setM44(m44);
374         if (m44 != 1) {
375             setIs2D(false);
376         }
377     }
378 
379     /**
380      * {@inheritDoc}
381      */
382     @Override
383     @JsxGetter
384     public double getA() {
385         return super.getA();
386     }
387 
388     /**
389      * Sets the {@code a} property.
390      * @param a the new value
391      */
392     @JsxSetter
393     public void setA(final double a) {
394         super.setM11(a);
395     }
396 
397     /**
398      * {@inheritDoc}
399      */
400     @Override
401     @JsxGetter
402     public double getB() {
403         return super.getB();
404     }
405 
406     /**
407      * Sets the {@code b} property.
408      * @param b the new value
409      */
410     @JsxSetter
411     public void setB(final double b) {
412         super.setM12(b);
413     }
414 
415     /**
416      * {@inheritDoc}
417      */
418     @Override
419     @JsxGetter
420     public double getC() {
421         return super.getC();
422     }
423 
424     /**
425      * Sets the {@code c} property.
426      * @param c the new value
427      */
428     @JsxSetter
429     public void setC(final double c) {
430         super.setM21(c);
431     }
432 
433     /**
434      * {@inheritDoc}
435      */
436     @Override
437     @JsxGetter
438     public double getD() {
439         return super.getD();
440     }
441 
442     /**
443      * Sets the {@code d} property.
444      * @param d the new value
445      */
446     @JsxSetter
447     public void setD(final double d) {
448         super.setM22(d);
449     }
450 
451     /**
452      * {@inheritDoc}
453      */
454     @Override
455     @JsxGetter
456     public double getE() {
457         return super.getE();
458     }
459 
460     /**
461      * Sets the {@code e} property.
462      * @param e the new value
463      */
464     @JsxSetter
465     public void setE(final double e) {
466         super.setM41(e);
467     }
468 
469     /**
470      * {@inheritDoc}
471      */
472     @Override
473     @JsxGetter
474     public double getF() {
475         return super.getF();
476     }
477 
478     /**
479      * Sets the {@code f} property.
480      * @param f the new value
481      */
482     @JsxSetter
483     public void setF(final double f) {
484         super.setM42(f);
485     }
486 
487     /**
488      * Inverts this matrix. If the matrix cannot be inverted,
489      * the components are all set to NaN and its is2D property is set to false.
490      * @return this matrix, inverted
491      */
492     @JsxFunction
493     public DOMMatrix invertSelf() {
494         invertSelfInternal();
495         return this;
496     }
497 
498     /**
499      * Post-multiplies this matrix with the given one (this = this * other).
500      *
501      * @param other the matrix to multiply with; this can be a matrix or an
502      *     object with matrix properties (DOMMatrixInit); {@code null} and {@code undefined}
503      *     are treated as identity matrix
504      * @return this matrix
505      */
506     @JsxFunction
507     public DOMMatrix multiplySelf(final Object other) {
508         multiplySelfInternal(fromMatrixInitForMultiply(other, "multiplySelf", getClassName()));
509         return this;
510     }
511 
512     /**
513      * Pre-multiplies this matrix with the given one (this = other * this).
514      *
515      * @param other the matrix to multiply with; this can be a matrix or an
516      *     object with matrix properties (DOMMatrixInit); {@code null} and {@code undefined}
517      *     are treated as identity matrix
518      * @return this matrix
519      */
520     @JsxFunction
521     public DOMMatrix preMultiplySelf(final Object other) {
522         preMultiplySelfInternal(fromMatrixInitForMultiply(other, "preMultiplySelf", getClassName()));
523         return this;
524     }
525 
526     /**
527      * Applies a translation to this matrix.
528      *
529      * @param tx the x component of the translating vector (default 0)
530      * @param ty the y component of the translating vector (default 0)
531      * @param tz the z component of the translating vector (default 0); if this is anything other
532      *     than 0, the matrix will be 3D
533      * @return this matrix
534      */
535     @JsxFunction
536     public DOMMatrix translateSelf(final Object tx, final Object ty, final Object tz) {
537         translateSelfInternal(toDouble(tx, 0), toDouble(ty, 0), toDouble(tz, 0));
538         return this;
539     }
540 
541     /**
542      * Scales this matrix by the given factors, centered on the given origin.
543      *
544      * @param scaleX the scale factor for the x-axis (default 1)
545      * @param scaleY the scale factor for the y-axis (default scaleX)
546      * @param scaleZ the scale factor for the z-axis (default 1)
547      * @param originX the x-coordinate of the origin (default 0)
548      * @param originY the y-coordinate of the origin (default 0)
549      * @param originZ the z-coordinate of the origin (default 0)
550      * @return this matrix
551      */
552     @JsxFunction
553     public DOMMatrix scaleSelf(final Object scaleX, final Object scaleY, final Object scaleZ,
554                 final Object originX, final Object originY, final Object originZ) {
555         final double sx = toDouble(scaleX, 1);
556         scaleSelfInternal(sx, toDouble(scaleY, sx), toDouble(scaleZ, 1),
557                 toDouble(originX, 0), toDouble(originY, 0), toDouble(originZ, 0));
558         return this;
559     }
560 
561     /**
562      * Scales all three axes of this matrix by the given factor, centered on the given origin.
563      *
564      * @param scale the scale factor (default 1)
565      * @param originX the x-coordinate of the origin (default 0)
566      * @param originY the y-coordinate of the origin (default 0)
567      * @param originZ the z-coordinate of the origin (default 0)
568      * @return this matrix
569      */
570     @JsxFunction
571     public DOMMatrix scale3dSelf(final Object scale, final Object originX, final Object originY,
572                 final Object originZ) {
573         scale3dSelfInternal(toDouble(scale, 1), toDouble(originX, 0), toDouble(originY, 0), toDouble(originZ, 0));
574         return this;
575     }
576 
577     /**
578      * Rotates this matrix by the specified angles.
579      * If only one argument is given, this is the rotation angle around the z-axis
580      * (a 2D rotation), otherwise the matrix is rotated around the z-axis, then around
581      * the y-axis and finally around the x-axis.
582      *
583      * @param rotX the rotation angle around the x-axis in degrees (or the rotation angle
584      *     around the z-axis if this is the only argument)
585      * @param rotY the rotation angle around the y-axis in degrees
586      * @param rotZ the rotation angle around the z-axis in degrees
587      * @return this matrix
588      */
589     @JsxFunction
590     public DOMMatrix rotateSelf(final Object rotX, final Object rotY, final Object rotZ) {
591         rotateSelfInternal(rotX, rotY, rotZ);
592         return this;
593     }
594 
595     /**
596      * Rotates this matrix by the angle between the specified vector and (1, 0).
597      *
598      * @param x the x component of the vector (default 0)
599      * @param y the y component of the vector (default 0)
600      * @return this matrix
601      */
602     @JsxFunction
603     public DOMMatrix rotateFromVectorSelf(final Object x, final Object y) {
604         rotateFromVectorSelfInternal(toDouble(x, 0), toDouble(y, 0));
605         return this;
606     }
607 
608     /**
609      * Rotates this matrix by the given angle around the specified axis.
610      *
611      * @param x the x component of the axis (default 0)
612      * @param y the y component of the axis (default 0)
613      * @param z the z component of the axis (default 0)
614      * @param angle the rotation angle in degrees (default 0)
615      * @return this matrix
616      */
617     @JsxFunction
618     public DOMMatrix rotateAxisAngleSelf(final Object x, final Object y, final Object z, final Object angle) {
619         rotateAxisAngleSelfInternal(toDouble(x, 0), toDouble(y, 0), toDouble(z, 0), toDouble(angle, 0));
620         return this;
621     }
622 
623     /**
624      * Skews this matrix along the x-axis by the specified angle.
625      *
626      * @param sx the angle in degrees (default 0)
627      * @return this matrix
628      */
629     @JsxFunction
630     public DOMMatrix skewXSelf(final Object sx) {
631         skewXSelfInternal(toDouble(sx, 0));
632         return this;
633     }
634 
635     /**
636      * Skews this matrix along the y-axis by the specified angle.
637      *
638      * @param sy the angle in degrees (default 0)
639      * @return this matrix
640      */
641     @JsxFunction
642     public DOMMatrix skewYSelf(final Object sy) {
643         skewYSelfInternal(toDouble(sy, 0));
644         return this;
645     }
646 
647     /**
648      * Replaces the values of this matrix with the matrix described by the given
649      * CSS transform list (e.g. {@code "translate(10px, 20px) rotate(45deg)"}).
650      *
651      * @param transformList the CSS transform list
652      * @return this matrix
653      */
654     @JsxFunction
655     public DOMMatrix setMatrixValue(final String transformList) {
656         setTransformList(transformList);
657         return this;
658     }
659 
660     /**
661      * Creates a new {@code DOMMatrix} from the given matrix or matrix properties.
662      *
663      * @param cx the current context
664      * @param scope the scope
665      * @param thisObj the scriptable this object
666      * @param args the arguments; the first one is the matrix or an object with matrix
667      *     properties (DOMMatrixInit)
668      * @param funObj the function object
669      * @return the new matrix
670      */
671     @JsxStaticFunction(functionName = "fromMatrix")
672     public static DOMMatrix fromMatrix(final Context cx, final VarScope scope,
673             final Scriptable thisObj, final Object[] args, final Function funObj) {
674         final DOMMatrixReadOnly init = fromMatrixInit(args.length > 0 ? args[0] : null,
675                 "fromMatrix", "DOMMatrix");
676         return newInstance(new DOMMatrix(), scope, "DOMMatrix", init);
677     }
678 
679     /**
680      * Creates a new {@code DOMMatrix} from the given Float32Array with 6 (2D)
681      * or 16 (3D) values.
682      *
683      * @param cx the current context
684      * @param scope the scope
685      * @param thisObj the scriptable this object
686      * @param args the arguments; the first one is the Float32Array
687      * @param funObj the function object
688      * @return the new matrix
689      */
690     @JsxStaticFunction(functionName = "fromFloat32Array")
691     public static DOMMatrix fromFloat32Array(final Context cx, final VarScope scope,
692             final Scriptable thisObj, final Object[] args, final Function funObj) {
693         final DOMMatrixReadOnly init = fromTypedArray(args, NativeFloat32Array.class, "fromFloat32Array", "DOMMatrix");
694         return newInstance(new DOMMatrix(), scope, "DOMMatrix", init);
695     }
696 
697     /**
698      * Creates a new {@code DOMMatrix} from the given Float64Array with 6 (2D)
699      * or 16 (3D) values.
700      *
701      * @param cx the current context
702      * @param scope the scope
703      * @param thisObj the scriptable this object
704      * @param args the arguments; the first one is the Float64Array
705      * @param funObj the function object
706      * @return the new matrix
707      */
708     @JsxStaticFunction(functionName = "fromFloat64Array")
709     public static DOMMatrix fromFloat64Array(final Context cx, final VarScope scope,
710             final Scriptable thisObj, final Object[] args, final Function funObj) {
711         final DOMMatrixReadOnly init = fromTypedArray(args, NativeFloat64Array.class, "fromFloat64Array", "DOMMatrix");
712         return newInstance(new DOMMatrix(), scope, "DOMMatrix", init);
713     }
714 }