Shader.java revision 866cf65cc3c53f67836c9157d5c661adfdbd25e1 
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 * Shader is the based class for objects that return horizontal spans of colors
21 * during drawing. A subclass of Shader is installed in a Paint calling
22 * paint.setShader(shader). After that any object (other than a bitmap) that is
23 * drawn with that paint will get its color(s) from the shader.
24 */
25public class Shader {
26    /**
27     * This is set by subclasses, but don't make it public.
28     */
29    private long native_instance;
30
31    private long native_with_local_matrix;
32
33    /**
34     * Initialization step that should be called by subclasses in their
35     * constructors. Calling again may result in memory leaks.
36     * @hide
37     */
38    protected void init(long ni) {
39        native_instance = ni;
40    }
41
42    private Matrix mLocalMatrix;
43
44    public enum TileMode {
45        /**
46         * replicate the edge color if the shader draws outside of its
47         * original bounds
48         */
49        CLAMP   (0),
50        /**
51         * repeat the shader's image horizontally and vertically
52         */
53        REPEAT  (1),
54        /**
55         * repeat the shader's image horizontally and vertically, alternating
56         * mirror images so that adjacent images always seam
57         */
58        MIRROR  (2);
59
60        TileMode(int nativeInt) {
61            this.nativeInt = nativeInt;
62        }
63        final int nativeInt;
64    }
65
66    /**
67     * Return true if the shader has a non-identity local matrix.
68     * @param localM If not null, it is set to the shader's local matrix.
69     * @return true if the shader has a non-identity local matrix
70     */
71    public boolean getLocalMatrix(Matrix localM) {
72        if (mLocalMatrix != null) {
73            localM.set(mLocalMatrix);
74            return !mLocalMatrix.isIdentity();
75        }
76        return false;
77    }
78
79    /**
80     * Set the shader's local matrix. Passing null will reset the shader's
81     * matrix to identity.
82     *
83     * Starting with {@link android.os.Build.VERSION_CODES#L}, this does not
84     * modify any Paints which use this Shader. In order to modify the Paint,
85     * you need to call {@link Paint#setShader} again. Further, any {@link ComposeShader}s
86     * created with this Shader will be unaffected.
87     *
88     * @param localM The shader's new local matrix, or null to specify identity
89     */
90    public void setLocalMatrix(Matrix localM) {
91        mLocalMatrix = localM;
92        native_with_local_matrix = nativeSetLocalMatrix(native_instance,
93                native_with_local_matrix, localM == null ? 0 : localM.native_instance);
94    }
95
96    protected void finalize() throws Throwable {
97        try {
98            super.finalize();
99        } finally {
100            nativeDestructor(native_instance, native_with_local_matrix);
101        }
102    }
103
104    /**
105     * @hide
106     */
107    protected Shader copy() {
108        final Shader copy = new Shader();
109        copyLocalMatrix(copy);
110        return copy;
111    }
112
113    /**
114     * @hide
115     */
116    protected void copyLocalMatrix(Shader dest) {
117        if (mLocalMatrix != null) {
118            final Matrix lm = new Matrix();
119            getLocalMatrix(lm);
120            dest.setLocalMatrix(lm);
121        } else {
122            dest.setLocalMatrix(null);
123        }
124    }
125
126    /* package */ long getNativeInstance() {
127        if (native_with_local_matrix != 0) {
128            return native_with_local_matrix;
129        }
130        return native_instance;
131    }
132
133    private static native void nativeDestructor(long native_shader, long native_with_local_matrix);
134    private static native long nativeSetLocalMatrix(long native_shader,
135            long native_with_local_matrix, long matrix_instance);
136}
137