com.jme3.util.NativeObject Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of jme3-core Show documentation
jMonkeyEngine is a 3D game engine for adventurous Java developers
The newest version!
/*
 * Copyright (c) 2009-2012 jMonkeyEngine
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 * * Redistributions of source code must retain the above copyright
 *   notice, this list of conditions and the following disclaimer.
 *
 * * Redistributions in binary form must reproduce the above copyright
 *   notice, this list of conditions and the following disclaimer in the
 *   documentation and/or other materials provided with the distribution.
 *
 * * Neither the name of 'jMonkeyEngine' nor the names of its contributors
 *   may be used to endorse or promote products derived from this software
 *   without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
 * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */
package com.jme3.util;

import java.nio.Buffer;

/**
 * Describes a native object. An encapsulation of a certain object 
 * on the native side of the graphics or audio library.
 * 
 * This class is used to track when OpenGL and OpenAL native objects are 
 * collected by the garbage collector, and then invoke the proper destructor
 * on the OpenGL library to delete it from memory.
 */
public abstract class NativeObject implements Cloneable {

    public static final int INVALID_ID = -1;
    
    protected static final int OBJTYPE_VERTEXBUFFER = 1,
                               OBJTYPE_TEXTURE      = 2,
                               OBJTYPE_FRAMEBUFFER  = 3,
                               OBJTYPE_SHADER       = 4,
                               OBJTYPE_SHADERSOURCE = 5,
                               OBJTYPE_AUDIOBUFFER  = 6,
                               OBJTYPE_AUDIOSTREAM  = 7,
                               OBJTYPE_FILTER       = 8;
    
    /**
     * The object manager to which this NativeObject is registered to.
     */
    protected NativeObjectManager objectManager = null;
    
    /**
     * The ID of the object, usually depends on its type.
     * Typically returned from calls like glGenTextures, glGenBuffers, etc.
     */
    protected int id = INVALID_ID;

    /**
     * A reference to a "handle". By hard referencing a certain object, it's
     * possible to find when a certain GLObject is no longer used, and to delete
     * its instance from the graphics library.
     */
    protected Object handleRef = null;

    /**
     * True if the data represented by this GLObject has been changed
     * and needs to be updated before used.
     */
    protected boolean updateNeeded = true;

    /**
     * Creates a new GLObject with the given type. Should be
     * called by the subclasses.
     * 
     * @param type The type that the subclass represents.
     */
    public NativeObject(){
        this.handleRef = new Object();
    }

    /**
     * Protected constructor that doesn't allocate handle ref.
     * This is used in subclasses for the createDestructableClone().
     */
    protected NativeObject(int id){
        this.id = id;
    }

    void setNativeObjectManager(NativeObjectManager objectManager) {
        this.objectManager = objectManager;
    }
    
    /**
     * Sets the ID of the NativeObject. This method is used in Renderer and must
     * not be called by the user.
     * 
     * @param id The ID to set
     */
    public void setId(int id){
        if (this.id != INVALID_ID) {
            throw new IllegalStateException("ID has already been set for this GL object.");
        }
        this.id = id;
    }

    /**
     * @return The ID of the object. Should not be used by user code in most
     * cases.
     */
    public int getId(){
        return id;
    }
    
    /**
     * Internal use only. Indicates that the object has changed
     * and its state needs to be updated.
     */
    public void setUpdateNeeded(){
        updateNeeded = true;
    }

    /**
     * Internal use only. Indicates that the state changes were applied.
     */
    public void clearUpdateNeeded(){
        updateNeeded = false;
    }

    /**
     * Internal use only. Check if {@link #setUpdateNeeded()} was called before.
     */
    public boolean isUpdateNeeded(){
        return updateNeeded;
    }

    @Override
    public String toString(){
        return "Native" + getClass().getSimpleName() + " " + id;
    }

    /**
     * This should create a deep clone. For a shallow clone, use
     * createDestructableClone().
     */
    @Override
    protected NativeObject clone() {
        try {
            NativeObject obj = (NativeObject) super.clone();
            obj.handleRef = new Object();
            obj.objectManager = null;
            obj.id = INVALID_ID;
            obj.updateNeeded = true;
            return obj;
        } catch (CloneNotSupportedException ex) {
            throw new AssertionError();
        }
    }

    /**
     * Deletes any associated native {@link Buffer buffers}.
     * This is necessary because it is unlikely that native buffers
     * will be garbage collected naturally (due to how GC works), therefore
     * the collection must be handled manually.
     * 
     * Only implementations that manage native buffers need to override
     * this method. Note that the behavior that occurs when a 
     * deleted native buffer is used is not defined, therefore this
     * method is protected
     */
    protected void deleteNativeBuffers() {
    }
    
    /**
     * Package-private version of {@link #deleteNativeBuffers() }, to be used
     * from the {@link NativeObjectManager}.
     */
    void deleteNativeBuffersInternal() {
        deleteNativeBuffers();
    }
    
    /**
     * Called when the GL context is restarted to reset all IDs. Prevents
     * "white textures" on display restart.
     */
    public abstract void resetObject();

    /**
     * Deletes the GL object from the GPU when it is no longer used. Called
     * automatically by the GL object manager.
     * 
     * @param rendererObject The renderer to be used to delete the object
     */
    public abstract void deleteObject(Object rendererObject);
    
    /**
     * Creates a shallow clone of this GL Object. The deleteObject method
     * should be functional for this object.
     */
    public abstract NativeObject createDestructableClone();
    
    /**
     * Returns a unique ID for this NativeObject. No other NativeObject shall
     * have the same ID.
     * 
     * @return unique ID for this NativeObject.
     */
    public abstract long getUniqueId();
    
    /**
     * Reclaims native resources used by this NativeObject.
     * It should be safe to call this method or even use the object
     * after it has been reclaimed, unless {@link NativeObjectManager#UNSAFE} is
     * set to true, in that case native buffers are also reclaimed which may
     * introduce instability.
     */
    public void dispose() {
        if (objectManager != null) {
            objectManager.enqueueUnusedObject(this);
        }
    }
}