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