Transform


1   /*******************************************************************************
2    * Copyright (c) 2000, 2007 IBM Corporation and others.
3    * All rights reserved. This program and the accompanying materials
4    * are made available under the terms of the Eclipse Public License v1.0
5    * which accompanies this distribution, and is available at
6    * http://www.eclipse.org/legal/epl-v10.html
7    *
8    * Contributors:
9    *     IBM Corporation - initial API and implementation
10   *******************************************************************************/
11  package org.eclipse.swt.graphics;
12  
13  import org.eclipse.swt.*;
14  import org.eclipse.swt.internal.gdip.*;
15  
16  /**
17   * Instances of this class represent transformation matrices for 
18   * points expressed as (x, y) pairs of floating point numbers.
19   * <p>
20   * Application code must explicitly invoke the <code>Transform.dispose()</code> 
21   * method to release the operating system resources managed by each instance
22   * when those instances are no longer required.
23   * </p>
24   * <p>
25   * This class requires the operating system's advanced graphics subsystem
26   * which may not be available on some platforms.
27   * </p>
28   * 
29   * @since 3.1
30   */
31  public class Transform extends Resource {
32  
33      /**
34       * the OS resource for the Transform
35       * (Warning: This field is platform dependent)
36       * <p>
37       * <b>IMPORTANT:</b> This field is <em>not</em> part of the SWT
38       * public API. It is marked public only so that it can be shared
39       * within the packages provided by SWT. It is not available on all
40       * platforms and should never be accessed from application code.
41       * </p>
42       */
43      public int handle;
44      
45  /**
46   * Constructs a new identity Transform.
47   * <p>
48   * This operation requires the operating system's advanced
49   * graphics subsystem which may not be available on some
50   * platforms.
51   * </p>
52   * 
53   * @param device the device on which to allocate the Transform
54   * 
55   * @exception IllegalArgumentException <ul>
56   *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
57   * </ul>
58   * @exception SWTException <ul>
59   *    <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li>
60   * </ul>
61   * @exception SWTError <ul>
62   *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained</li>
63   * </ul>
64   * 
65   * @see #dispose()
66   */
67  public Transform (Device device) {
68      this(device, 1, 0, 0, 1, 0, 0);
69  }
70  
71  /**
72   * Constructs a new Transform given an array of elements that represent the 
73   * matrix that describes the transformation.
74   * <p>
75   * This operation requires the operating system's advanced
76   * graphics subsystem which may not be available on some
77   * platforms.
78   * </p>
79   * 
80   * @param device the device on which to allocate the Transform
81   * @param elements an array of floats that describe the transformation matrix
82   * 
83   * @exception IllegalArgumentException <ul>
84   *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device, or the elements array is null</li>
85   *    <li>ERROR_INVALID_ARGUMENT - if the elements array is too small to hold the matrix values</li>
86   * </ul>
87   * @exception SWTException <ul>
88   *    <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li>
89   * </ul>
90   * @exception SWTError <ul>
91   *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained</li>
92   * </ul>
93   * 
94   * @see #dispose()
95   */
96  public Transform(Device device, float[] elements) {
97      this (device, checkTransform(elements)[0], elements[1], elements[2], elements[3], elements[4], elements[5]);
98  }
99  
100 /**
101  * Constructs a new Transform given all of the elements that represent the 
102  * matrix that describes the transformation.
103  * <p>
104  * This operation requires the operating system's advanced
105  * graphics subsystem which may not be available on some
106  * platforms.
107  * </p>
108  * 
109  * @param device the device on which to allocate the Transform
110  * @param m11 the first element of the first row of the matrix
111  * @param m12 the second element of the first row of the matrix
112  * @param m21 the first element of the second row of the matrix
113  * @param m22 the second element of the second row of the matrix
114  * @param dx the third element of the first row of the matrix
115  * @param dy the third element of the second row of the matrix
116  * 
117  * @exception IllegalArgumentException <ul>
118  *    <li>ERROR_NULL_ARGUMENT - if device is null and there is no current device</li>
119  * </ul>
120  * @exception SWTException <ul>
121  *    <li>ERROR_NO_GRAPHICS_LIBRARY - if advanced graphics are not available</li>
122  * </ul>
123  * @exception SWTError <ul>
124  *    <li>ERROR_NO_HANDLES if a handle for the Transform could not be obtained</li>
125  * </ul>
126  * 
127  * @see #dispose()
128  */
129 public Transform (Device device, float m11, float m12, float m21, float m22, float dx, float dy) {
130     if (device == null) device = Device.getDevice();
131     if (device == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
132     this.device = device;
133     device.checkGDIP();
134     handle = Gdip.Matrix_new(m11, m12, m21, m22, dx, dy);
135     if (handle == 0) SWT.error(SWT.ERROR_NO_HANDLES);
136     if (device.tracking) device.new_Object(this);
137 }
138 
139 static float[] checkTransform(float[] elements) {
140     if (elements == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
141     if (elements.length < 6) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
142     return elements;
143 }
144 
145 /**
146  * Disposes of the operating system resources associated with
147  * the Transform. Applications must dispose of all Transforms that
148  * they allocate.
149  */
150 public void dispose() {
151     if (handle == 0) return;
152     if (device.isDisposed()) return;
153     Gdip.Matrix_delete(handle);
154     handle = 0;
155     if (device.tracking) device.dispose_Object(this);
156     device = null;
157 }
158 
159 /**
160  * Fills the parameter with the values of the transformation matrix
161  * that the receiver represents, in the order {m11, m12, m21, m22, dx, dy}.
162  *
163  * @param elements array to hold the matrix values
164  *
165  * @exception SWTException <ul>
166  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
167  * </ul>
168  * @exception IllegalArgumentException <ul>
169  *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
170  *    <li>ERROR_INVALID_ARGUMENT - if the parameter is too small to hold the matrix values</li>
171  * </ul>
172  */
173 public void getElements(float[] elements) {
174     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
175     if (elements == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
176     if (elements.length < 6) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
177     Gdip.Matrix_GetElements(handle, elements);
178 }
179 
180 /**
181  * Modifies the receiver such that the matrix it represents becomes the
182  * the mathematical inverse of the matrix it previously represented. 
183  *
184  * @exception SWTException <ul>
185  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
186  *    <li>ERROR_CANNOT_INVERT_MATRIX - if the matrix is not invertible</li>
187  * </ul>
188  */
189 public void invert() {
190     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
191     if (Gdip.Matrix_Invert(handle) != 0) SWT.error(SWT.ERROR_CANNOT_INVERT_MATRIX);
192 }
193 
194 /**
195  * Returns <code>true</code> if the Transform has been disposed,
196  * and <code>false</code> otherwise.
197  * <p>
198  * This method gets the dispose state for the Transform.
199  * When a Transform has been disposed, it is an error to
200  * invoke any other method using the Transform.
201  *
202  * @return <code>true</code> when the Transform is disposed, and <code>false</code> otherwise
203  */
204 public boolean isDisposed() {
205     return handle == 0;
206 }
207 
208 /**
209  * Returns <code>true</code> if the Transform represents the identity matrix
210  * and false otherwise.
211  *
212  * @return <code>true</code> if the receiver is an identity Transform, and <code>false</code> otherwise
213  */
214 public boolean isIdentity() {
215     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
216     return Gdip.Matrix_IsIdentity(handle);
217 }
218 
219 /**
220  * Modifies the receiver such that the matrix it represents becomes the
221  * the result of multiplying the matrix it previously represented by the
222  * argument. 
223  *
224  * @param matrix the matrix to multiply the receiver by
225  * 
226  * @exception SWTException <ul>
227  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
228  * </ul>
229  * @exception IllegalArgumentException <ul>
230  *    <li>ERROR_NULL_ARGUMENT - if the parameter is null</li>
231  *    <li>ERROR_INVALID_ARGUMENT - if the parameter has been disposed</li>
232  * </ul>
233  */
234 public void multiply(Transform matrix) {
235     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
236     if (matrix == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
237     if (matrix.isDisposed()) SWT.error(SWT.ERROR_INVALID_ARGUMENT);
238     Gdip.Matrix_Multiply(handle, matrix.handle, Gdip.MatrixOrderPrepend);
239 }
240 
241 /**
242  * Modifies the receiver so that it represents a transformation that is
243  * equivalent to its previous transformation rotated by the specified angle.
244  * The angle is specified in degrees and for the identity transform 0 degrees
245  * is at the 3 o'clock position. A positive value indicates a clockwise rotation
246  * while a negative value indicates a counter-clockwise rotation.
247  *
248  * @param angle the angle to rotate the transformation by
249  * 
250  * @exception SWTException <ul>
251  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
252  * </ul>
253  */
254 public void rotate(float angle) {
255     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
256     Gdip.Matrix_Rotate(handle, angle, Gdip.MatrixOrderPrepend);
257 }
258 
259 /**
260  * Modifies the receiver so that it represents a transformation that is
261  * equivalent to its previous transformation scaled by (scaleX, scaleY).
262  * 
263  * @param scaleX the amount to scale in the X direction
264  * @param scaleY the amount to scale in the Y direction
265  * 
266  * @exception SWTException <ul>
267  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
268  * </ul>
269  */
270 public void scale(float scaleX, float scaleY) {
271     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
272     Gdip.Matrix_Scale(handle, scaleX, scaleY, Gdip.MatrixOrderPrepend);
273 }
274 
275 /**
276  * Modifies the receiver to represent a new transformation given all of
277  * the elements that represent the matrix that describes that transformation.
278  * 
279  * @param m11 the first element of the first row of the matrix
280  * @param m12 the second element of the first row of the matrix
281  * @param m21 the first element of the second row of the matrix
282  * @param m22 the second element of the second row of the matrix
283  * @param dx the third element of the first row of the matrix
284  * @param dy the third element of the second row of the matrix
285  * 
286  * @exception SWTException <ul>
287  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
288  * </ul>
289  */
290 public void setElements(float m11, float m12, float m21, float m22, float dx, float dy) {
291     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
292     Gdip.Matrix_SetElements(handle, m11, m12, m21, m22, dx, dy);
293 }
294 
295 /** 
296  * Given an array containing points described by alternating x and y values,
297  * modify that array such that each point has been replaced with the result of
298  * applying the transformation represented by the receiver to that point.
299  *
300  * @param pointArray an array of alternating x and y values to be transformed
301  *
302  * @exception IllegalArgumentException <ul>
303  *    <li>ERROR_NULL_ARGUMENT - if the point array is null</li>
304  * </ul>    
305  * @exception SWTException <ul>
306  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
307  * </ul>
308  */
309 public void transform(float[] pointArray) {
310     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
311     if (pointArray == null) SWT.error(SWT.ERROR_NULL_ARGUMENT);
312     Gdip.Matrix_TransformPoints(handle, pointArray, pointArray.length / 2);
313 }
314 
315 /**
316  * Modifies the receiver so that it represents a transformation that is
317  * equivalent to its previous transformation translated by (offsetX, offsetY).
318  * 
319  * @param offsetX the distance to translate in the X direction
320  * @param offsetY the distance to translate in the Y direction
321  * 
322  * @exception SWTException <ul>
323  *    <li>ERROR_GRAPHIC_DISPOSED - if the receiver has been disposed</li>
324  * </ul>
325  */
326 public void translate(float offsetX, float offsetY) {
327     if (isDisposed()) SWT.error(SWT.ERROR_GRAPHIC_DISPOSED);
328     Gdip.Matrix_Translate(handle, offsetX, offsetY, Gdip.MatrixOrderPrepend);
329 }
330 
331 /**
332  * Returns a string containing a concise, human-readable
333  * description of the receiver.
334  *
335  * @return a string representation of the receiver
336  */
337 public String   toString() {
338     if (isDisposed()) return "Transform {*DISPOSED*}";
339     float[] elements = new float[6];
340     getElements(elements);
341     return "Transform {" + elements [0] + "," + elements [1] + "," +elements [2] + "," +elements [3] + "," +elements [4] + "," +elements [5] + "}";
342 }
343 
344 }
345
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags