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
33package com.jme3.system;
34
35import com.jme3.input.JoyInput;
36import com.jme3.input.KeyInput;
37import com.jme3.input.MouseInput;
38import com.jme3.input.TouchInput;
39import com.jme3.renderer.Renderer;
40
41/**
42 * Represents a rendering context within the engine.
43 */
44public 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