1/*
2 * Copyright (c) 2009-2010 jMonkeyEngine
3 * All rights reserved.
4 *
5 * Redistribution and use in source and binary forms, with or without
6 * modification, are permitted provided that the following conditions are
7 * met:
8 *
9 * * Redistributions of source code must retain the above copyright
10 *   notice, this list of conditions and the following disclaimer.
11 *
12 * * Redistributions in binary form must reproduce the above copyright
13 *   notice, this list of conditions and the following disclaimer in the
14 *   documentation and/or other materials provided with the distribution.
15 *
16 * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
17 *   may be used to endorse or promote products derived from this software
18 *   without specific prior written permission.
19 *
20 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
22 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
23 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
24 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
27 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
28 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
29 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32
33package com.jme3.util;
34
35/**
36 * Describes a native object. An encapsulation of a certain object
37 * on the native side of the graphics or audio library.
38 *
39 * This class is used to track when OpenGL and OpenAL native objects are
40 * collected by the garbage collector, and then invoke the proper destructor
41 * on the OpenGL library to delete it from memory.
42 */
43public abstract class NativeObject implements Cloneable {
44
45    /**
46     * The ID of the object, usually depends on its type.
47     * Typically returned from calls like glGenTextures, glGenBuffers, etc.
48     */
49    protected int id = -1;
50
51    /**
52     * A reference to a "handle". By hard referencing a certain object, it's
53     * possible to find when a certain GLObject is no longer used, and to delete
54     * its instance from the graphics library.
55     */
56    protected Object handleRef = null;
57
58    /**
59     * True if the data represented by this GLObject has been changed
60     * and needs to be updated before used.
61     */
62    protected boolean updateNeeded = true;
63
64    /**
65     * The type of the GLObject, usually specified by a subclass.
66     */
67    protected final Class<?> type;
68
69    /**
70     * Creates a new GLObject with the given type. Should be
71     * called by the subclasses.
72     *
73     * @param type The type that the subclass represents.
74     */
75    public NativeObject(Class<?> type){
76        this.type = type;
77        this.handleRef = new Object();
78    }
79
80    /**
81     * Protected constructor that doesn't allocate handle ref.
82     * This is used in subclasses for the createDestructableClone().
83     */
84    protected NativeObject(Class<?> type, int id){
85        this.type = type;
86        this.id = id;
87    }
88
89    /**
90     * Sets the ID of the GLObject. This method is used in Renderer and must
91     * not be called by the user.
92     * @param id The ID to set
93     */
94    public void setId(int id){
95        if (this.id != -1)
96            throw new IllegalStateException("ID has already been set for this GL object.");
97
98        this.id = id;
99    }
100
101    /**
102     * @return The ID of the object. Should not be used by user code in most
103     * cases.
104     */
105    public int getId(){
106        return id;
107    }
108
109    /**
110     * Internal use only. Indicates that the object has changed
111     * and its state needs to be updated.
112     */
113    public void setUpdateNeeded(){
114        updateNeeded = true;
115    }
116
117    /**
118     * Internal use only. Indicates that the state changes were applied.
119     */
120    public void clearUpdateNeeded(){
121        updateNeeded = false;
122    }
123
124    /**
125     * Internal use only. Check if {@link #setUpdateNeeded()} was called before.
126     */
127    public boolean isUpdateNeeded(){
128        return updateNeeded;
129    }
130
131    @Override
132    public String toString(){
133        return "Native" + type.getSimpleName() + " " + id;
134    }
135
136    /**
137     * This should create a deep clone. For a shallow clone, use
138     * createDestructableClone().
139     */
140    @Override
141    protected NativeObject clone(){
142        try{
143            NativeObject obj = (NativeObject) super.clone();
144            obj.handleRef = new Object();
145            obj.id = -1;
146            obj.updateNeeded = true;
147            return obj;
148        }catch (CloneNotSupportedException ex){
149            throw new AssertionError();
150        }
151    }
152
153    /**
154     * Called when the GL context is restarted to reset all IDs. Prevents
155     * "white textures" on display restart.
156     */
157    public abstract void resetObject();
158
159    /**
160     * Deletes the GL object from the GPU when it is no longer used. Called
161     * automatically by the GL object manager.
162     *
163     * @param rendererObject The renderer to be used to delete the object
164     */
165    public abstract void deleteObject(Object rendererObject);
166
167    /**
168     * Creates a shallow clone of this GL Object. The deleteObject method
169     * should be functional for this object.
170     */
171    public abstract NativeObject createDestructableClone();
172}
173