ICanvas.d.ts 24 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482
  1. /**
  2. * Class used to abstract a canvas
  3. */
  4. export interface ICanvas {
  5. /**
  6. * Canvas width.
  7. */
  8. width: number;
  9. /**
  10. * Canvas height.
  11. */
  12. height: number;
  13. /**
  14. * returns a drawing context on the canvas.
  15. * @param contextType context identifier.
  16. * @param contextAttributes context attributes.
  17. * @returns ICanvasRenderingContext object.
  18. */
  19. getContext(contextType: string, contextAttributes?: any): ICanvasRenderingContext;
  20. /**
  21. * returns a data URI containing a representation of the image in the format specified by the type parameter.
  22. * @param mime the image format.
  23. * @returns string containing the requested data URI.
  24. */
  25. toDataURL(mime: string): string;
  26. /**
  27. * Removes the canvas from the document.
  28. * Offscreen canvases don't have the remove function, so we need to make it optional.
  29. */
  30. remove?(): void;
  31. }
  32. /**
  33. * Class used to abstract am image to use with the canvas and its context
  34. */
  35. export interface IImage {
  36. /**
  37. * onload callback.
  38. */
  39. onload: ((this: GlobalEventHandlers, ev: Event) => any) | null;
  40. /**
  41. * Error callback.
  42. */
  43. onerror: ((this: GlobalEventHandlers, ev: Event) => any) | null;
  44. /**
  45. * Image source.
  46. */
  47. src: string;
  48. /**
  49. * Image width.
  50. */
  51. readonly width: number;
  52. /**
  53. * Image height.
  54. */
  55. readonly height: number;
  56. /**
  57. * The original height of the image resource before sizing.
  58. */
  59. readonly naturalHeight: number;
  60. /**
  61. * The original width of the image resource before sizing.
  62. */
  63. readonly naturalWidth: number;
  64. /**
  65. * provides support for CORS, defining how the element handles crossorigin requests,
  66. * thereby enabling the configuration of the CORS requests for the element's fetched data.
  67. */
  68. crossOrigin: string | null;
  69. /**
  70. * provides support for referrer policy on xhr load request,
  71. * it is used to control the request header.
  72. */
  73. referrerPolicy: string;
  74. }
  75. /**
  76. * Class used to abstract a canvas gradient
  77. */
  78. export interface ICanvasGradient {
  79. /**
  80. * adds a new color stop, defined by an offset and a color, to a given canvas gradient.
  81. * @param offset A number between 0 and 1, inclusive, representing the position of the color stop. 0 represents the start of the gradient and 1 represents the end.
  82. * @param color value representing the color of the stop.
  83. */
  84. addColorStop(offset: number, color: string): void;
  85. }
  86. /**
  87. * Class used to abstract a text measurement
  88. */
  89. export interface ITextMetrics {
  90. /**
  91. * Text width.
  92. */
  93. readonly width: number;
  94. /**
  95. * distance (in pixels) parallel to the baseline from the alignment point given by the CanvasRenderingContext2D.textAlign
  96. * property to the left side of the bounding rectangle of the given text
  97. */
  98. readonly actualBoundingBoxLeft: number;
  99. /**
  100. * distance (in pixels) parallel to the baseline from the alignment point given by the CanvasRenderingContext2D.textAlign
  101. * property to the right side of the bounding rectangle of the given text
  102. */
  103. readonly actualBoundingBoxRight: number;
  104. /**
  105. * distance (in pixels) from the horizontal line indicated by the CanvasRenderingContext2D.textBaseline
  106. * property to the top side of the bounding rectangle of the given text
  107. */
  108. readonly actualBoundingBoxAscent: number;
  109. /**
  110. * distance (in pixels) from the horizontal line indicated by the CanvasRenderingContext2D.textBaseline
  111. * property to the bottom side of the bounding rectangle of the given text
  112. */
  113. readonly actualBoundingBoxDescent: number;
  114. }
  115. /**
  116. * Class used to abstract a matrix
  117. */
  118. export interface DOMMatrix {
  119. /**
  120. * A Boolean flag whose value is true if the matrix was initialized as a 2D matrix. If false, the matrix is 3D.
  121. */
  122. is2D: boolean;
  123. /**
  124. * A Boolean whose value is true if the matrix is the identity matrix. The identity matrix is one in which every value is 0 except those on the main diagonal from top-left to bottom-right corner (in other words, where the offsets in each direction are equal).
  125. */
  126. isIdentity: boolean;
  127. /**
  128. * The following double-precision floating-point values represent the components of a matrix which are required in order to perform 2D rotations and translations.
  129. */
  130. a: number;
  131. /**
  132. * The following double-precision floating-point values represent the components of a matrix which are required in order to perform 2D rotations and translations.
  133. */
  134. b: number;
  135. /**
  136. * The following double-precision floating-point values represent the components of a matrix which are required in order to perform 2D rotations and translations.
  137. */
  138. c: number;
  139. /**
  140. * The following double-precision floating-point values represent the components of a matrix which are required in order to perform 2D rotations and translations.
  141. */
  142. d: number;
  143. /**
  144. * The following double-precision floating-point values represent the components of a matrix which are required in order to perform 2D rotations and translations.
  145. */
  146. e: number;
  147. /**
  148. * The following double-precision floating-point values represent the components of a matrix which are required in order to perform 2D rotations and translations.
  149. */
  150. f: number;
  151. /**
  152. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  153. */
  154. m11: number;
  155. /**
  156. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  157. */
  158. m12: number;
  159. /**
  160. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  161. */
  162. m13: number;
  163. /**
  164. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  165. */
  166. m14: number;
  167. /**
  168. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  169. */
  170. m21: number;
  171. /**
  172. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  173. */
  174. m22: number;
  175. /**
  176. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  177. */
  178. m23: number;
  179. /**
  180. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  181. */
  182. m24: number;
  183. /**
  184. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  185. */
  186. m31: number;
  187. /**
  188. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  189. */
  190. m32: number;
  191. /**
  192. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  193. */
  194. m33: number;
  195. /**
  196. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  197. */
  198. m34: number;
  199. /**
  200. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  201. */
  202. m41: number;
  203. /**
  204. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  205. */
  206. m42: number;
  207. /**
  208. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  209. */
  210. m43: number;
  211. /**
  212. * The following are double-precision floating-point values representing each component of a 4×4 matrix, where m11 through m14 are the first column, m21 through m24 are the second column, and so forth.
  213. */
  214. m44: number;
  215. }
  216. /**
  217. * Class used to abstract canvas rendering
  218. */
  219. export interface ICanvasRenderingContext {
  220. /**
  221. * Defines the type of corners where two lines meet. Possible values: round, bevel, miter (default).
  222. */
  223. lineJoin: string;
  224. /**
  225. * Miter limit ratio. Default 10.
  226. */
  227. miterLimit: number;
  228. /**
  229. * Font setting. Default value 10px sans-serif.
  230. */
  231. font: string;
  232. /**
  233. * Color or style to use for the lines around shapes. Default #000 (black).
  234. */
  235. strokeStyle: string | ICanvasGradient;
  236. /**
  237. * Color or style to use inside shapes. Default #000 (black).
  238. */
  239. fillStyle: string | ICanvasGradient;
  240. /**
  241. * Alpha value that is applied to shapes and images before they are composited onto the canvas. Default 1.0 (opaque).
  242. */
  243. globalAlpha: number;
  244. /**
  245. * Color of the shadow. Default: fully-transparent black.
  246. */
  247. shadowColor: string;
  248. /**
  249. * Specifies the blurring effect. Default: 0.
  250. */
  251. shadowBlur: number;
  252. /**
  253. * Horizontal distance the shadow will be offset. Default: 0.
  254. */
  255. shadowOffsetX: number;
  256. /**
  257. * Vertical distance the shadow will be offset. Default: 0.
  258. */
  259. shadowOffsetY: number;
  260. /**
  261. * Width of lines. Default 1.0.
  262. */
  263. lineWidth: number;
  264. /**
  265. * canvas is a read-only reference to ICanvas.
  266. */
  267. readonly canvas: ICanvas;
  268. /**
  269. * Sets all pixels in the rectangle defined by starting point (x, y) and size (width, height) to transparent black, erasing any previously drawn content.
  270. * @param x The x-axis coordinate of the rectangle's starting point.
  271. * @param y The y-axis coordinate of the rectangle's starting point.
  272. * @param width The rectangle's width. Positive values are to the right, and negative to the left.
  273. * @param height The rectangle's height. Positive values are down, and negative are up.
  274. */
  275. clearRect(x: number, y: number, width: number, height: number): void;
  276. /**
  277. * Saves the current drawing style state using a stack so you can revert any change you make to it using restore().
  278. */
  279. save(): void;
  280. /**
  281. * Restores the drawing style state to the last element on the 'state stack' saved by save().
  282. */
  283. restore(): void;
  284. /**
  285. * Draws a filled rectangle at (x, y) position whose size is determined by width and height.
  286. * @param x The x-axis coordinate of the rectangle's starting point.
  287. * @param y The y-axis coordinate of the rectangle's starting point.
  288. * @param width The rectangle's width. Positive values are to the right, and negative to the left.
  289. * @param height The rectangle's height. Positive values are down, and negative are up.
  290. */
  291. fillRect(x: number, y: number, width: number, height: number): void;
  292. /**
  293. * Adds a scaling transformation to the canvas units by x horizontally and by y vertically.
  294. * @param x Scaling factor in the horizontal direction. A negative value flips pixels across the vertical axis. A value of 1 results in no horizontal scaling.
  295. * @param y Scaling factor in the vertical direction. A negative value flips pixels across the horizontal axis. A value of 1 results in no vertical scaling.
  296. */
  297. scale(x: number, y: number): void;
  298. /**
  299. * Adds a rotation to the transformation matrix. The angle argument represents a clockwise rotation angle and is expressed in radians.
  300. * @param angle The rotation angle, clockwise in radians. You can use degree * Math.PI / 180 to calculate a radian from a degree.
  301. */
  302. rotate(angle: number): void;
  303. /**
  304. * Adds a translation transformation by moving the canvas and its origin x horizontally and y vertically on the grid.
  305. * @param x Distance to move in the horizontal direction. Positive values are to the right, and negative to the left.
  306. * @param y Distance to move in the vertical direction. Positive values are down, and negative are up.
  307. */
  308. translate(x: number, y: number): void;
  309. /**
  310. * Paints a rectangle which has a starting point at (x, y) and has a w width and an h height onto the canvas, using the current stroke style.
  311. * @param x The x-axis coordinate of the rectangle's starting point.
  312. * @param y The y-axis coordinate of the rectangle's starting point.
  313. * @param width The rectangle's width. Positive values are to the right, and negative to the left.
  314. * @param height The rectangle's height. Positive values are down, and negative are up.
  315. */
  316. strokeRect(x: number, y: number, width: number, height: number): void;
  317. /**
  318. * Creates a path for a rectangle at position (x, y) with a size that is determined by width and height.
  319. * @param x The x-axis coordinate of the rectangle's starting point.
  320. * @param y The y-axis coordinate of the rectangle's starting point.
  321. * @param width The rectangle's width. Positive values are to the right, and negative to the left.
  322. * @param height The rectangle's height. Positive values are down, and negative are up.
  323. */
  324. rect(x: number, y: number, width: number, height: number): void;
  325. /**
  326. * Creates a clipping path from the current sub-paths. Everything drawn after clip() is called appears inside the clipping path only.
  327. */
  328. clip(): void;
  329. /**
  330. * Paints data from the given ImageData object onto the bitmap. If a dirty rectangle is provided, only the pixels from that rectangle are painted.
  331. * @param imageData An ImageData object containing the array of pixel values.
  332. * @param dx Horizontal position (x coordinate) at which to place the image data in the destination canvas.
  333. * @param dy Vertical position (y coordinate) at which to place the image data in the destination canvas.
  334. */
  335. putImageData(imageData: ImageData, dx: number, dy: number): void;
  336. /**
  337. * Adds a circular arc to the current path.
  338. * @param x The horizontal coordinate of the arc's center.
  339. * @param y The vertical coordinate of the arc's center.
  340. * @param radius The arc's radius. Must be positive.
  341. * @param startAngle The angle at which the arc starts in radians, measured from the positive x-axis.
  342. * @param endAngle The angle at which the arc ends in radians, measured from the positive x-axis.
  343. * @param anticlockwise An optional Boolean. If true, draws the arc counter-clockwise between the start and end angles. The default is false (clockwise).
  344. */
  345. arc(x: number, y: number, radius: number, startAngle: number, endAngle: number, anticlockwise?: boolean): void;
  346. /**
  347. * Starts a new path by emptying the list of sub-paths. Call this method when you want to create a new path.
  348. */
  349. beginPath(): void;
  350. /**
  351. * Causes the point of the pen to move back to the start of the current sub-path. It tries to draw a straight line from the current point to the start.
  352. * If the shape has already been closed or has only one point, this function does nothing.
  353. */
  354. closePath(): void;
  355. /**
  356. * Moves the starting point of a new sub-path to the (x, y) coordinates.
  357. * @param x The x-axis (horizontal) coordinate of the point.
  358. * @param y The y-axis (vertical) coordinate of the point.
  359. */
  360. moveTo(x: number, y: number): void;
  361. /**
  362. * Connects the last point in the current sub-path to the specified (x, y) coordinates with a straight line.
  363. * @param x The x-axis coordinate of the line's end point.
  364. * @param y The y-axis coordinate of the line's end point.
  365. */
  366. lineTo(x: number, y: number): void;
  367. /**
  368. * Adds a quadratic Bézier curve to the current path.
  369. * @param cpx The x-axis coordinate of the control point.
  370. * @param cpy The y-axis coordinate of the control point.
  371. * @param x The x-axis coordinate of the end point.
  372. * @param y The y-axis coordinate of the end point.
  373. */
  374. quadraticCurveTo(cpx: number, cpy: number, x: number, y: number): void;
  375. /**
  376. * Returns a TextMetrics object.
  377. * @param text The text String to measure.
  378. * @returns ITextMetrics A ITextMetrics object.
  379. */
  380. measureText(text: string): ITextMetrics;
  381. /**
  382. * Strokes the current sub-paths with the current stroke style.
  383. */
  384. stroke(): void;
  385. /**
  386. * Fills the current sub-paths with the current fill style.
  387. */
  388. fill(): void;
  389. /**
  390. * Draws the specified image. This method is available in multiple formats, providing a great deal of flexibility in its use.
  391. * @param image An element to draw into the context.
  392. * @param sx The x-axis coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
  393. * @param sy The y-axis coordinate of the top left corner of the sub-rectangle of the source image to draw into the destination context.
  394. * @param sWidth The width of the sub-rectangle of the source image to draw into the destination context. If not specified, the entire rectangle from the coordinates specified by sx and sy to the bottom-right corner of the image is used.
  395. * @param sHeight The height of the sub-rectangle of the source image to draw into the destination context.
  396. * @param dx The x-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
  397. * @param dy The y-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
  398. * @param dWidth The width to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in width when drawn.
  399. * @param dHeight The height to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in height when drawn.
  400. */
  401. drawImage(image: any, sx: number, sy: number, sWidth: number, sHeight: number, dx: number, dy: number, dWidth: number, dHeight: number): void;
  402. /**
  403. * Draws the specified image. This method is available in multiple formats, providing a great deal of flexibility in its use.
  404. * @param image An element to draw into the context.
  405. * @param dx The x-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
  406. * @param dy The y-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
  407. * @param dWidth The width to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in width when drawn.
  408. * @param dHeight The height to draw the image in the destination canvas. This allows scaling of the drawn image. If not specified, the image is not scaled in height when drawn.
  409. */
  410. drawImage(image: any, dx: number, dy: number, dWidth: number, dHeight: number): void;
  411. /**
  412. * Draws the specified image. This method is available in multiple formats, providing a great deal of flexibility in its use.
  413. * @param image An element to draw into the context.
  414. * @param dx The x-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
  415. * @param dy The y-axis coordinate in the destination canvas at which to place the top-left corner of the source image.
  416. */
  417. drawImage(image: any, dx: number, dy: number): void;
  418. /**
  419. * Returns an ImageData object representing the underlying pixel data for the area of the canvas denoted by the rectangle which starts at (sx, sy) and has an sw width and sh height.
  420. * @param sx The x-axis coordinate of the top-left corner of the rectangle from which the ImageData will be extracted.
  421. * @param sy The y-axis coordinate of the top-left corner of the rectangle from which the ImageData will be extracted.
  422. * @param sw The width of the rectangle from which the ImageData will be extracted. Positive values are to the right, and negative to the left.
  423. * @param sh The height of the rectangle from which the ImageData will be extracted. Positive values are down, and negative are up.
  424. * @returns ImageData An ImageData object containing the image data for the rectangle of the canvas specified.
  425. */
  426. getImageData(sx: number, sy: number, sw: number, sh: number): ImageData;
  427. /**
  428. * Sets the current line dash pattern.
  429. * @param segments An Array of numbers that specify distances to alternately draw a line and a gap (in coordinate space units).
  430. */
  431. setLineDash(segments: Array<number>): void;
  432. /**
  433. * Draws (fills) a given text at the given (x, y) position.
  434. * @param text A String specifying the text string to render into the context. The text is rendered using the settings specified by font, textAlign, textBaseline, and direction.
  435. * @param x The x-axis coordinate of the point at which to begin drawing the text, in pixels.
  436. * @param y The y-axis coordinate of the baseline on which to begin drawing the text, in pixels.
  437. * @param maxWidth The maximum number of pixels wide the text may be once rendered. If not specified, there is no limit to the width of the text.
  438. */
  439. fillText(text: string, x: number, y: number, maxWidth?: number): void;
  440. /**
  441. * Draws (strokes) a given text at the given (x, y) position.
  442. * @param text A String specifying the text string to render into the context. The text is rendered using the settings specified by font, textAlign, textBaseline, and direction.
  443. * @param x The x-axis coordinate of the point at which to begin drawing the text, in pixels.
  444. * @param y The y-axis coordinate of the baseline on which to begin drawing the text, in pixels.
  445. * @param maxWidth The maximum number of pixels wide the text may be once rendered. If not specified, there is no limit to the width of the text.
  446. */
  447. strokeText(text: string, x: number, y: number, maxWidth?: number): void;
  448. /**
  449. * Creates a linear gradient along the line given by the coordinates represented by the parameters.
  450. * @param x0 The x-axis coordinate of the start point.
  451. * @param y0 The y-axis coordinate of the start point.
  452. * @param x1 The x-axis coordinate of the end point.
  453. * @param y1 The y-axis coordinate of the end point.
  454. * @returns ICanvasGradient A linear ICanvasGradient initialized with the specified line.
  455. */
  456. createLinearGradient(x0: number, y0: number, x1: number, y1: number): ICanvasGradient;
  457. /**
  458. * Creates a linear gradient along the line given by the coordinates represented by the parameters.
  459. * @param x0 The x-axis coordinate of the start circle.
  460. * @param y0 The y-axis coordinate of the start circle.
  461. * @param r0 The radius of the start circle. Must be non-negative and finite.
  462. * @param x1 The x-axis coordinate of the end point.
  463. * @param y1 The y-axis coordinate of the end point.
  464. * @param r1 The radius of the end circle. Must be non-negative and finite.
  465. * @returns ICanvasGradient A linear ICanvasGradient initialized with the two specified circles.
  466. */
  467. createRadialGradient(x0: number, y0: number, r0: number, x1: number, y1: number, r1: number): ICanvasGradient;
  468. /**
  469. * Resets the current transform to matrix composed with a, b, c, d, e, f.
  470. * @param a Horizontal scaling. A value of 1 results in no scaling.
  471. * @param b Vertical skewing.
  472. * @param c Horizontal skewing.
  473. * @param d Vertical scaling. A value of 1 results in no scaling.
  474. * @param e Horizontal translation (moving).
  475. * @param f Vertical translation (moving).
  476. */
  477. setTransform(a: number, b: number, c: number, d: number, e: number, f: number): void;
  478. /**
  479. * Retrieves the current transformation matrix being applied to the context.
  480. */
  481. getTransform(): DOMMatrix;
  482. }