Home | History | Annotate | Download | only in system 
      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.system;
     34 
     35 import com.jme3.input.JoyInput;
     36 import com.jme3.input.KeyInput;
     37 import com.jme3.input.MouseInput;
     38 import com.jme3.input.TouchInput;
     39 import com.jme3.renderer.Renderer;
     40 
     41 /**
     42  * Represents a rendering context within the engine.
     43  */
     44 public interface JmeContext {
     45 
     46     /**
     47      * The type of context.
     48      */
     49     public enum Type {
     50         /**
     51          * A display can represent a windowed or a fullscreen-exclusive display.
     52          * If windowed, the graphics are rendered to a new on-screen surface
     53          * enclosed in a window defined by the operating system. Implementations
     54          * are encouraged to not use AWT or Swing to create the OpenGL display
     55          * but rather use native operating system functions to set up a native
     56          * display with the windowing system.
     57          */
     58         Display,
     59 
     60         /**
     61          * A canvas type context makes a rendering surface available as an
     62          * AWT {@link java.awt.Canvas} object that can be embedded in a Swing/AWT
     63          * frame. To retrieve the Canvas object, you should cast the context
     64          * to {@link JmeCanvasContext}.
     65          */
     66         Canvas,
     67 
     68         /**
     69          * An <code>OffscreenSurface</code> is a context that is not visible
     70          * by the user. The application can use the offscreen surface to do
     71          * General Purpose GPU computations or render a scene into a buffer
     72          * in order to save it as a screenshot, video or send through a network.
     73          */
     74         OffscreenSurface,
     75 
     76         /**
     77          * A <code>Headless</code> context is not visible and does not have
     78          * any drawable surface. The implementation does not provide any
     79          * display, input, or sound support.
     80          */
     81         Headless;
     82     }
     83 
     84     /**
     85      * @return The type of the context.
     86      */
     87     public Type getType();
     88 
     89     /**
     90      * @param settings the display settings to use for the created context. If
     91      * the context has already been created, then <code>restart()</code> must be called
     92      * for the changes to be applied.
     93      */
     94     public void setSettings(AppSettings settings);
     95 
     96     /**
     97      * Sets the listener that will receive events relating to context
     98      * creation, update, and destroy.
     99      */
    100     public void setSystemListener(SystemListener listener);
    101 
    102     /**
    103      * @return The current display settings. Note that they might be
    104      * different from the ones set with setDisplaySettings() if the context
    105      * was restarted or the settings changed internally.
    106      */
    107     public AppSettings getSettings();
    108 
    109     /**
    110      * @return The renderer for this context, or null if not created yet.
    111      */
    112     public Renderer getRenderer();
    113 
    114     /**
    115      * @return Mouse input implementation. May be null if not available.
    116      */
    117     public MouseInput getMouseInput();
    118 
    119     /**
    120      * @return Keyboard input implementation. May be null if not available.
    121      */
    122     public KeyInput getKeyInput();
    123 
    124     /**
    125      * @return Joystick input implementation. May be null if not available.
    126      */
    127     public JoyInput getJoyInput();
    128 
    129     /**
    130      * @return Touch device input implementation. May be null if not available.
    131      */
    132     public TouchInput getTouchInput();
    133 
    134     /**
    135      * @return The timer for this context, or null if not created yet.
    136      */
    137     public Timer getTimer();
    138 
    139     /**
    140      * Sets the title of the display (if available). This does nothing
    141      * for fullscreen, headless, or canvas contexts.
    142      * @param title The new title of the display.
    143      */
    144     public void setTitle(String title);
    145 
    146     /**
    147      * @return True if the context has been created but not yet destroyed.
    148      */
    149     public boolean isCreated();
    150 
    151     /**
    152      * @return True if the context contains a valid render surface,
    153      * if any of the rendering methods in {@link Renderer} are called
    154      * while this is <code>false</code>, then the result is undefined.
    155      */
    156     public boolean isRenderable();
    157 
    158     /**
    159      * @param enabled If enabled, the context will automatically flush
    160      * frames to the video card (swap buffers) after an update cycle.
    161      */
    162     public void setAutoFlushFrames(boolean enabled);
    163 
    164     /**
    165      * Creates the context and makes it active.
    166      *
    167      * @param waitFor If true, will wait until context has initialized.
    168      */
    169     public void create(boolean waitFor);
    170 
    171     /**
    172      * Destroys and then re-creates the context. This should be called after
    173      * the display settings have been changed.
    174      */
    175     public void restart();
    176 
    177     /**
    178      * Destroys the context completely, making it inactive.
    179      *
    180      * @param waitFor If true, will wait until the context is destroyed fully.
    181      */
    182     public void destroy(boolean waitFor);
    183 
    184 }
    185