/*****************************************************************************
 *                     Yumetech, Inc Copyright (c) 2005
 *                               Java Source
 *
 * This source is licensed under the BSD-style License
 * Please read http://www.opensource.org/licenses/bsd-license.php for more
 * information or docs/BSD.txt in the downloaded code.
 *
 * This software comes with the standard NO WARRANTY disclaimer for any
 * purpose. Use it at your own risk. If there's a problem you get to fix it.
 *
 ****************************************************************************/

package org.j3d.opengl.swt.internal.ri;

// External imports
import javax.media.opengl.GLContext;
import javax.media.opengl.GLException;

// Local imports
// None

/**
 * Extension interface for describing onscreen surfaces that need
 * locking capabilities to avoid multithreaded access issues.
 *
 * @author Justin Couch
 * @version $Revision: 1.1 $
 */
public interface SurfaceController
{
    /**
     * The lock cannot succeed because the underlying surface hasn't been
     * created yet.
     */
    public static final int SURFACE_NOT_READY = 1;

    /** The lock has succeeded by the underlying surface changed. */
    public static final int SURFACE_CHANGED = 2;

    /** The lock succeed with no other effects */
    public static final int SUCCESS = 3;

    /**
     * Lock the surface now so that we can draw to it.
     *
     * @return One of the surface constants from this interface
     * @throws GLException The surface is already locked by someone else
     */
    public int lockSurface() throws GLException;

    /**
     * Check to see if the surface is currently locked.
     *
     * @return true if the surface is locked, false otherwise
     */
    public boolean isLockedSurface();

    /**
     * Release the surface back to the OS. This may throw an exception if the
     * surface is already unlocked at this point.
     *
     * @throws GLException The surface is already unlocked
     */
    public void unlockSurface() throws GLException;
}