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.asset; 34 35 import com.jme3.audio.AudioData; 36 import com.jme3.audio.AudioKey; 37 import com.jme3.font.BitmapFont; 38 import com.jme3.material.Material; 39 import com.jme3.scene.Spatial; 40 import com.jme3.shader.Shader; 41 import com.jme3.shader.ShaderKey; 42 import com.jme3.texture.Texture; 43 import java.util.List; 44 45 /** 46 * <code>AssetManager</code> provides an interface for managing the data assets 47 * of a jME3 application. 48 */ 49 public 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 */ addClassLoader(ClassLoader loader)56 public void addClassLoader(ClassLoader loader); 57 58 /** 59 * Remove a ClassLoader from the list of registered ClassLoaders 60 */ removeClassLoader(ClassLoader loader)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 */ getClassLoaders()67 public List<ClassLoader> getClassLoaders(); 68 69 /** 70 * Registers a loader for the given extensions. 71 * @param loaderClassName 72 * @param extensions 73 */ registerLoader(String loaderClassName, String ... extensions)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 */ registerLocator(String rootPath, String locatorClassName)86 public void registerLocator(String rootPath, String locatorClassName); 87 88 /** 89 * 90 * @param loaderClass 91 * @param extensions 92 */ registerLoader(Class<? extends AssetLoader> loaderClass, String ... extensions)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 */ registerLocator(String rootPath, Class<? extends AssetLocator> locatorClass)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 */ unregisterLocator(String rootPath, Class<? extends AssetLocator> locatorClass)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 */ setAssetEventListener(AssetEventListener listener)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 */ locateAsset(AssetKey<?> key)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 */ loadAsset(AssetKey<T> key)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 */ loadAsset(String name)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 */ loadTexture(TextureKey key)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 */ loadTexture(String name)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 */ loadAudio(AudioKey key)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 */ loadAudio(String name)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 */ loadModel(ModelKey key)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 */ loadModel(String name)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 */ loadMaterial(String name)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 */ loadShader(ShaderKey key)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 */ loadFont(String name)264 public BitmapFont loadFont(String name); 265 } 266