1 /*
2  * Copyright (C) 2006 The Android Open Source Project
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  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.graphics;
18 
19 import android.compat.annotation.UnsupportedAppUsage;
20 
21 /**
22  * A camera instance can be used to compute 3D transformations and
23  * generate a matrix that can be applied, for instance, on a
24  * {@link Canvas}.
25  */
26 public class Camera {
27     /**
28      * Creates a new camera, with empty transformations.
29      */
Camera()30     public Camera() {
31         nativeConstructor();
32     }
33 
34     /**
35      * Saves the camera state. Each save should be balanced
36      * with a call to {@link #restore()}.
37      *
38      * @see #save()
39      */
save()40     public native void save();
41 
42     /**
43      * Restores the saved state, if any.
44      *
45      * @see #restore()
46      */
restore()47     public native void restore();
48 
49     /**
50      * Applies a translation transform on all three axis.
51      *
52      * @param x The distance to translate by on the X axis
53      * @param y The distance to translate by on the Y axis
54      * @param z The distance to translate by on the Z axis
55      */
translate(float x, float y, float z)56     public native void translate(float x, float y, float z);
57 
58     /**
59      * Applies a rotation transform around the X axis.
60      *
61      * @param deg The angle of rotation around the X axis, in degrees
62      *
63      * @see #rotateY(float)
64      * @see #rotateZ(float)
65      * @see #rotate(float, float, float)
66      */
rotateX(float deg)67     public native void rotateX(float deg);
68 
69     /**
70      * Applies a rotation transform around the Y axis.
71      *
72      * @param deg The angle of rotation around the Y axis, in degrees
73      *
74      * @see #rotateX(float)
75      * @see #rotateZ(float)
76      * @see #rotate(float, float, float)
77      */
rotateY(float deg)78     public native void rotateY(float deg);
79 
80     /**
81      * Applies a rotation transform around the Z axis.
82      *
83      * @param deg The angle of rotation around the Z axis, in degrees
84      *
85      * @see #rotateX(float)
86      * @see #rotateY(float)
87      * @see #rotate(float, float, float)
88      */
rotateZ(float deg)89     public native void rotateZ(float deg);
90 
91     /**
92      * Applies a rotation transform around all three axis.
93      *
94      * @param x The angle of rotation around the X axis, in degrees
95      * @param y The angle of rotation around the Y axis, in degrees
96      * @param z The angle of rotation around the Z axis, in degrees
97      *
98      * @see #rotateX(float)
99      * @see #rotateY(float)
100      * @see #rotateZ(float)
101      */
rotate(float x, float y, float z)102     public native void rotate(float x, float y, float z);
103 
104     /**
105      * Gets the x location of the camera.
106      *
107      * @see #setLocation(float, float, float)
108      */
getLocationX()109     public native float getLocationX();
110 
111     /**
112      * Gets the y location of the camera.
113      *
114      * @see #setLocation(float, float, float)
115      */
getLocationY()116     public native float getLocationY();
117 
118     /**
119      * Gets the z location of the camera.
120      *
121      * @see #setLocation(float, float, float)
122      */
getLocationZ()123     public native float getLocationZ();
124 
125     /**
126      * Sets the location of the camera. The default location is set at
127      * 0, 0, -8.
128      *
129      * @param x The x location of the camera
130      * @param y The y location of the camera
131      * @param z The z location of the camera
132      */
setLocation(float x, float y, float z)133     public native void setLocation(float x, float y, float z);
134 
135     /**
136      * Computes the matrix corresponding to the current transformation
137      * and copies it to the supplied matrix object.
138      *
139      * @param matrix The matrix to copy the current transforms into
140      */
getMatrix(Matrix matrix)141     public void getMatrix(Matrix matrix) {
142         nativeGetMatrix(matrix.native_instance);
143     }
144 
145     /**
146      * Computes the matrix corresponding to the current transformation
147      * and applies it to the specified Canvas.
148      *
149      * @param canvas The Canvas to set the transform matrix onto
150      */
applyToCanvas(Canvas canvas)151     public void applyToCanvas(Canvas canvas) {
152         nativeApplyToCanvas(canvas.getNativeCanvasWrapper());
153     }
154 
dotWithNormal(float dx, float dy, float dz)155     public native float dotWithNormal(float dx, float dy, float dz);
156 
finalize()157     protected void finalize() throws Throwable {
158         try {
159             nativeDestructor();
160             native_instance = 0;
161         } finally {
162             super.finalize();
163         }
164     }
165 
nativeConstructor()166     private native void nativeConstructor();
nativeDestructor()167     private native void nativeDestructor();
nativeGetMatrix(long native_matrix)168     private native void nativeGetMatrix(long native_matrix);
nativeApplyToCanvas(long native_canvas)169     private native void nativeApplyToCanvas(long native_canvas);
170 
171     @UnsupportedAppUsage
172     long native_instance;
173 }
174