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 33 package 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 */ 43 public 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 */ NativeObject(Class<?> type)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 */ NativeObject(Class<?> type, int id)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 */ setId(int id)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 */ getId()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 */ setUpdateNeeded()113 public void setUpdateNeeded(){ 114 updateNeeded = true; 115 } 116 117 /** 118 * Internal use only. Indicates that the state changes were applied. 119 */ clearUpdateNeeded()120 public void clearUpdateNeeded(){ 121 updateNeeded = false; 122 } 123 124 /** 125 * Internal use only. Check if {@link #setUpdateNeeded()} was called before. 126 */ isUpdateNeeded()127 public boolean isUpdateNeeded(){ 128 return updateNeeded; 129 } 130 131 @Override toString()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 clone()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 */ resetObject()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 */ deleteObject(Object rendererObject)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 */ createDestructableClone()171 public abstract NativeObject createDestructableClone(); 172 } 173