Home | History | Annotate | Download | only in util 
      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      */
     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