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.asset;
34
35import com.jme3.audio.AudioData;
36import com.jme3.audio.AudioKey;
37import com.jme3.font.BitmapFont;
38import com.jme3.material.Material;
39import com.jme3.scene.Spatial;
40import com.jme3.shader.Shader;
41import com.jme3.shader.ShaderKey;
42import com.jme3.texture.Texture;
43import java.util.List;
44
45/**
46 * <code>AssetManager</code> provides an interface for managing the data assets
47 * of a jME3 application.
48 */
49public interface AssetManager {
50
51    /**
52     * Adds a ClassLoader that is used to load *Classes* that are needed for Assets like j3o models.
53     * This does *not* allow loading assets from that classpath, use registerLocator for that.
54     * @param loader A ClassLoader that Classes in asset files can be loaded from
55     */
56    public void addClassLoader(ClassLoader loader);
57
58    /**
59     * Remove a ClassLoader from the list of registered ClassLoaders
60     */
61    public void removeClassLoader(ClassLoader loader);
62
63    /**
64     * Retrieve the list of registered ClassLoaders that are used for loading Classes from
65     * asset files.
66     */
67    public List<ClassLoader> getClassLoaders();
68
69    /**
70     * Registers a loader for the given extensions.
71     * @param loaderClassName
72     * @param extensions
73     */
74    public void registerLoader(String loaderClassName, String ... extensions);
75
76    /**
77     * Registers an {@link AssetLocator} by using a class name, instead of
78     * a class instance. See the {@link AssetManager#registerLocator(java.lang.String, java.lang.Class) }
79     * method for more information.
80     *
81     * @param rootPath The root path from which to locate assets, implementation
82     * dependent.
83     * @param locatorClassName The full class name of the {@link AssetLocator}
84     * implementation.
85     */
86    public void registerLocator(String rootPath, String locatorClassName);
87
88    /**
89     *
90     * @param loaderClass
91     * @param extensions
92     */
93    public void registerLoader(Class<? extends AssetLoader> loaderClass, String ... extensions);
94
95    /**
96     * Registers the given locator class for locating assets with this
97     * <code>AssetManager</code>. {@link AssetLocator}s are invoked in the order
98     * they were registered, to locate the asset by the {@link AssetKey}.
99     * Once an {@link AssetLocator} returns a non-null AssetInfo, it is sent
100     * to the {@link AssetLoader} to load the asset.
101     * Once a locator is registered, it can be removed via
102     * {@link #unregisterLocator(java.lang.String, java.lang.Class) }.
103     *
104     * @param rootPath Specifies the root path from which to locate assets
105     * for the given {@link AssetLocator}. The purpose of this parameter
106     * depends on the type of the {@link AssetLocator}.
107     * @param locatorClass The class type of the {@link AssetLocator} to register.
108     *
109     * @see AssetLocator#setRootPath(java.lang.String)
110     * @see AssetLocator#locate(com.jme3.asset.AssetManager, com.jme3.asset.AssetKey)
111     * @see #unregisterLocator(java.lang.String, java.lang.Class)
112     */
113    public void registerLocator(String rootPath, Class<? extends AssetLocator> locatorClass);
114
115    /**
116     * Unregisters the given locator class. This essentially undoes the operation
117     * done by {@link #registerLocator(java.lang.String, java.lang.Class) }.
118     *
119     * @param rootPath Should be the same as the root path specified in {@link
120     * #registerLocator(java.lang.String, java.lang.Class) }.
121     * @param locatorClass The locator class to unregister
122     */
123    public void unregisterLocator(String rootPath, Class<? extends AssetLocator> locatorClass);
124
125    /**
126     * Set an {@link AssetEventListener} to receive events from this
127     * <code>AssetManager</code>. There can only be one {@link  AssetEventListener}
128     * associated with an <code>AssetManager</code>
129     *
130     * @param listener
131     */
132    public void setAssetEventListener(AssetEventListener listener);
133
134    /**
135     * Manually locates an asset with the given {@link AssetKey}. This method
136     * should be used for debugging or internal uses. <br/>
137     * The call will attempt to locate the asset by invoking the
138     * {@link AssetLocator} that are registered with this <code>AssetManager</code>,
139     * in the same way that the {@link AssetManager#loadAsset(com.jme3.asset.AssetKey) }
140     * method locates assets.
141     *
142     * @param key The {@link AssetKey} to locate.
143     * @return The {@link AssetInfo} object returned from the {@link AssetLocator}
144     * that located the asset, or null if the asset cannot be located.
145     */
146    public AssetInfo locateAsset(AssetKey<?> key);
147
148    /**
149     * Load an asset from a key, the asset will be located
150     * by one of the {@link AssetLocator} implementations provided in the
151     * {@link AssetManager#registerLocator(java.lang.String, java.lang.Class) }
152     * call. If located successfully, it will be loaded via the the appropriate
153     * {@link AssetLoader} implementation based on the file's extension, as
154     * specified in the call
155     * {@link AssetManager#registerLoader(java.lang.Class, java.lang.String[]) }.
156     *
157     * @param <T> The object type that will be loaded from the AssetKey instance.
158     * @param key The AssetKey
159     * @return The loaded asset, or null if it was failed to be located
160     * or loaded.
161     */
162    public <T> T loadAsset(AssetKey<T> key);
163
164    /**
165     * Load a named asset by name, calling this method
166     * is the same as calling
167     * <code>
168     * loadAsset(new AssetKey(name)).
169     * </code>
170     *
171     * @param name The name of the asset to load.
172     * @return The loaded asset, or null if failed to be loaded.
173     *
174     * @see AssetManager#loadAsset(com.jme3.asset.AssetKey)
175     */
176    public Object loadAsset(String name);
177
178    /**
179     * Loads texture file, supported types are BMP, JPG, PNG, GIF,
180     * TGA and DDS.
181     *
182     * @param key The {@link TextureKey} to use for loading.
183     * @return The loaded texture, or null if failed to be loaded.
184     *
185     * @see AssetManager#loadAsset(com.jme3.asset.AssetKey)
186     */
187    public Texture loadTexture(TextureKey key);
188
189    /**
190     * Loads texture file, supported types are BMP, JPG, PNG, GIF,
191     * TGA and DDS.
192     *
193     * @param name The name of the texture to load.
194     * @return The texture that was loaded
195     *
196     * @see AssetManager#loadAsset(com.jme3.asset.AssetKey)
197     */
198    public Texture loadTexture(String name);
199
200    /**
201     * Load audio file, supported types are WAV or OGG.
202     * @param key
203     * @return The audio data loaded
204     *
205     * @see AssetManager#loadAsset(com.jme3.asset.AssetKey)
206     */
207    public AudioData loadAudio(AudioKey key);
208
209    /**
210     * Load audio file, supported types are WAV or OGG.
211     * The file is loaded without stream-mode.
212     * @param name
213     * @return The audio data loaded
214     *
215     * @see AssetManager#loadAsset(com.jme3.asset.AssetKey)
216     */
217    public AudioData loadAudio(String name);
218
219    /**
220     * Loads a named model. Models can be jME3 object files (J3O) or
221     * OgreXML/OBJ files.
222     * @param key
223     * @return The model that was loaded
224     *
225     * @see AssetManager#loadAsset(com.jme3.asset.AssetKey)
226     */
227    public Spatial loadModel(ModelKey key);
228
229    /**
230     * Loads a named model. Models can be jME3 object files (J3O) or
231     * OgreXML/OBJ files.
232     * @param name
233     * @return The model that was loaded
234     *
235     * @see AssetManager#loadAsset(com.jme3.asset.AssetKey)
236     */
237    public Spatial loadModel(String name);
238
239    /**
240     * Load a material (J3M) file.
241     * @param name
242     * @return The material that was loaded
243     *
244     * @see AssetManager#loadAsset(com.jme3.asset.AssetKey)
245     */
246    public Material loadMaterial(String name);
247
248    /**
249     * Loads shader file(s), shouldn't be used by end-user in most cases.
250     *
251     * @see AssetManager#loadAsset(com.jme3.asset.AssetKey)
252     */
253    public Shader loadShader(ShaderKey key);
254
255    /**
256     * Load a font file. Font files are in AngelCode text format,
257     * and are with the extension "fnt".
258     *
259     * @param name
260     * @return The font loaded
261     *
262     * @see AssetManager#loadAsset(com.jme3.asset.AssetKey)
263     */
264    public BitmapFont loadFont(String name);
265}
266