Package edu.cornell.gdiac.graphics.obj

Class ObjParser

java.lang.Object
edu.cornell.gdiac.graphics.obj.ObjParser
public class ObjParser extends Object
This class generates an AST for an OBJ file (and its associated MTL files).

This parser only provides limited support for OBJ and MTL files. We only support polygonal objects, with no freeform drawing. We also only support basic illumination (illum values 0-2) with bump mapping.

This class does not actually produce render data, as that is potentially time consuming. That step should be left up to an asset loader. Instead, this parser simply collates the information about the OBJ model into a single AST, as its data can potentially be spread over multiple files (including MTL and texture files).

Because OBJ data is spread over mutliple files, this parser is stateful. That means it can expand the current ModelInfo data by reading other files.

  • Field Details

    • debug

      public boolean debug
      Whether to emit debugging information

    • textures

      public com.badlogic.gdx.utils.ObjectMap<String,MaterialInfo.LightMap> textures
      The information for the referenced textures

    • materials

      public com.badlogic.gdx.utils.ObjectMap<String,MaterialLib> materials
      The information for previously parsed MTL files

    • models

      public com.badlogic.gdx.utils.ObjectMap<String,ModelInfo> models
      The information for previously parsed OBJ files

  • Constructor Details

    • ObjParser

      public ObjParser()
      Creates a new OBJ parser.

      This is a fairly lightweight object. Therefore it is safe to use this constructor with new (though std::make_shared is prefered).

    • ObjParser

      public ObjParser(com.badlogic.gdx.assets.loaders.FileHandleResolver resolver)
      Creates a new OBJ parser with the given resolver.

      This is a fairly lightweight object. Therefore it is safe to use this constructor with new (though std::make_shared is prefered).

      Parameters:
      resolver - The file resolver

  • Method Details

    • parseObj

      public ModelInfo parseObj(String source, boolean recurse)
      Returns the information for the given OBJ file.

      This method blocks until the OBJ file is read. If recurse is true, it will also read any imported MTL files (assuming that they are in the same directory as the OBJ files). If recurse ifs false, it will create entries in the ModelInfo object for the imported libraries with no values. The user can add the information for these libraries later.

      This is a stateful parser. Once an OBJ file has been parsed, its data can be retreived at any time with getObj(java.lang.String). This method uses the path to the OBJ file as the key.

      Parameters:
      source - The path to the OBJ file
      recurse - Whether to load any files referenced by source
      Returns:
      the information for the given OBJ file.

    • parseJson

      public ModelInfo parseJson(com.badlogic.gdx.utils.JsonValue json)
      Returns the information for the given OBJ model.

      This method allows you to specify the location of the OBJ file, its MTL file, and any associated textures as a single JSON entry. An OBJ Json entry has the following values:

      • "file": The path to the OBJ file
      • "mtls": An object of key:value pairs defining MTL libraries

      The "mtls" entry is optional. For each MTL library, the key should match the name of the MTL file referenced in the obj file. If there are any missing MTL libraries (or the "mtls" entry is missing entirely), then the loader will attempt to use the same directory as the OBJ file.

      An MTL entry is either a string (which is a reference to the path to the MTL file) or a JSON object. Such a JSON object would have the following values:

      • "file": The path to the MTL file
      • "textures": An object of key:value pairs defining textures

      The "textures" entry is optional. For each texture, the key should match the name of the texture in the MTL file. Any missing textures will attempt to be loaded if the parsing depth is correct.

      The values for the texture entries should be strings or JSONs. If they are string, they should be either be a key referencing a previously loaded texture, or a path to the texture file (the loader interprets it as a path only if there is no key with that name). If it is a JSON, then the JSON should follow the same rules as TextureParser.

      Parameters:
      json - The JSON value specifying the OBJ model
      Returns:
      the information for the given OBJ model.

    • parseObj

      public ModelInfo parseObj(String key, String source, boolean recurse)
      Returns the information for the given OBJ file.

      This method blocks until the OBJ file is read. If recurse is true, it will also read any imported MTL files (assuming that they are in the same directory as the OBJ files). If recurse ifs false, it will create entries in the ModelInfo object for the imported libraries with no values. The user can add the information for these libraries later.

      This is a stateful parser. Once an OBJ file has been parsed, its data can be retreived at any time with getObj(java.lang.String). This method uses the specified key for retrieval.

      Parameters:
      key - The retrieval key
      source - The path to the OBJ file
      recurse - Whether to load any files referenced by source
      Returns:
      the information for the given OBJ file.

    • getObj

      public ModelInfo getObj(String key)
      Returns the information for a previously parsed OBJ file.

      This method returns null if the OBJ file has not been yet parsed. For models that have been parsed, the retrieval key was specified at the time of parsing.

      Parameters:
      key - The retrieval key
      Returns:
      the information for a previously parsed OBJ file.

    • parseMtl

      public MaterialLib parseMtl(String source)
      Returns the information for the given MTL file.

      This method blocks until the MTL file is read. However, it does not read any imported files (like the Texture files). Instead, it assigns the MaterialInfo.LightMap attributes according the settings in the MTL file.

      This method does not link a MaterialInfo to a ModelInfo object. That is the responsibility of the user.

      This is a stateful parser. Once a MTL file has been parsed, its data can be retreived at any time with getMtl(java.lang.String). This method uses the path to the MTL file as the key.

      Parameters:
      source - The path to the MTL file
      Returns:
      the information for the given MTL file.

    • parseMtl

      public MaterialLib parseMtl(String key, String source)
      Returns the information for the given MTL file.

      This method blocks until the MTL file is read. However, it does not read any imported files (like the Texture files). Instead, it assigns the MaterialInfo.LightMap attributes according the settings in the MTL file.

      This method does not link a MaterialInfo to a ModelInfo object. That is the responsibility of the user.

      This is a stateful parser. Once a MTL file has been parsed, its data can be retreived at any time with getMtl(java.lang.String). This method uses the specified key for retrieval.

      Parameters:
      key - The retrieval key
      source - The path to the MTL file
      Returns:
      the information for the given MTL file.

    • getMtl

      public MaterialLib getMtl(String key)
      Returns the information for a previously parsed MTL file.

      This method returns null if the MTL file has not been yet parsed. For materials that have been parsed, the retrieval key was specified at the time of parsing.

      Parameters:
      key - The retrieval key
      Returns:
      the information for a previously parsed MTL file.

    • clear

      public void clear()
      Clears all internal caches.

      This is a stateful parser. Once an OBJ or MTL file has been parsed, its data can be retrieved at any time with getObj(java.lang.String) or getMtl(java.lang.String), respectively. This method clears all such state so that those methods return nullptr until a new file is parsed.