/*
 * Copyright (c) 2016, Metron, Inc.
 * 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 Metron, Inc. 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 METRON, INC. 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.metsci.glimpse.canvas;

import javax.media.opengl.GLAutoDrawable;
import javax.media.opengl.GLContext;
import javax.media.opengl.GLEventListener;
import javax.media.opengl.GLProfile;
import javax.media.opengl.GLRunnable;

import com.metsci.glimpse.context.GlimpseBounds;
import com.metsci.glimpse.context.GlimpseContext;
import com.metsci.glimpse.context.GlimpseTarget;
import com.metsci.glimpse.layout.GlimpseLayout;
import com.metsci.glimpse.painter.base.GlimpsePainter;

/**
 * A heavy weight target for Glimpse rendering. Represents
 * the base component onto which all Glimpse rendering
 * is ultimately performed. GlimpseCanvas provides a facade
 * that hides the implementation details of the specific
 * widget toolkit (Swt or Swing) being used, allowing most
 * Glimpse applications to be easily ported between the two.
 *
 * @author ulman
 */
public interface GlimpseCanvas extends GlimpseTarget
{
    public GLProfile getGLProfile( );

    public GLAutoDrawable getGLDrawable( );

    public GLContext getGLContext( );

    public GlimpseContext getGlimpseContext( );

    public GlimpseBounds getTargetBounds( );

    /**
     * Lays out any {@link com.metsci.glimpse.layout.GlimpseLayout} instances
     * attached to the GlimpseCanvas and paints all
     * {@link com.metsci.glimpse.painter.base.GlimpsePainter} instances attached
     * to the GlimpseLayouts.
     */
    public void paint( );

    /**
     * Destroys the native surface which this canvas draws to. Does not dispose of GL resources associated
     * with GlimpsePainters and GlimpseLayouts attached to the GlimpseCanvas (as these may be attached to other
     * GlimpseCanvases as well). Disposing of Glimpse resources can be done via {@code #disposeAttached()}.
     *
     * @see #disposeAttached()
     */
    public void destroy( );

    /**
     * Disposes native resources of GlimpseLayouts and GlimpsePainters associated with the GlimpseCanvas.
     *
     * @see #destroy()
     */
    public void disposeAttached( );

    /**
     * A convenience method which is equivalent to:
     *
     * <code>
     * disposeAttached( );
     * destroy( );
     * </code>
     */
    public void dispose( );

    /**
     * <p>Calls {@link GlimpsePainter#dispose(GlimpseContext)} the next time the GLContext associated with
     * this GlimpseCanvas is active. Generally this call is equivalent to:</p>
     *
     * <code>
     *  this.getGLDrawable( ).invoke( false, new GLRunnable( )
     *  {
     *      @Override
     *      public boolean run( GLAutoDrawable drawable )
     *      {
     *          painter.dispose( getGlimpseContext( ) );
     *          return true;
     *      }
     *  } );
     * </code>
     *
     * <p>The GlimpsePainter should be removed from all GlimpseLayouts via
     * {@link GlimpseLayout#removePainter(GlimpsePainter)} before disposePainter is called. After the GlimpsePainter
     * is disposed, it will no longer be valid for drawing on any GlimpseCanvas.</p>
     */
    public void disposePainter( GlimpsePainter painter );

    /**
     * @return whether or not {@code #dispose()} has been successfully called. Once true, this GlimpseCanvas is no longer valid for rendering.
     */
    public boolean isDestroyed( );

    /**
     * Called when {@link GLEventListener#dispose(GLAutoDrawable)} event is fired by the {@link GLAutoDrawable} associated with the
     * GlimpseCanvas. This can happen for reasons other than the window containing the GlimpseCanvas being closed (for example, moving
     * the window between physical monitors or moving the container between docks in a docking framework). Thus, GlimpsePainters and
     * GlimpseLayouts attached to this GlimpseCanvas should generally not be disposed when this callback occurs.
     */
    public void addDisposeListener( GLRunnable runnable );

    /**
     * Returns the scale factors needed to convert the _native_ pixel coordinates to
     * the _window_ pixel coordinates. This only really matters on displays like like
     * Macbook Retina.
     *
     * @return the scale factors as {scaleX, scaleY}
     */
    public int[] getSurfaceScale( );
}