.. include:: definitions.rstinc

.. _locating-files:

======================================
Locating files and resources
======================================

All resources (images, models, scripts) and runtime libraries (.dll/.so) are located using the singleton class :cpp:`agxIO::Environment`. Currently there are two separate types of files:
  -	Runtime files: .dll (WIN32), .so (Unix), .dylib (OSX)
  -	Resource files: (.png, .obj, .png, .cfg, .agxPy, .schema, .agxKernel)
  - Textures and models: (For example .png, jpg, .obj, .stl etc.)

The path where these files can be found can be either controlled using environment variables as specified in :numref:`environment-variables`, or programmatically using the *agxIO::Environment class*. This should be done before creating any other AGX object where file reading will be involved.

.. code-block:: c++

  // Get a file path container to where runtime files are searched
  agx::FilePathContainer& runtime_path =
    agxIO::Environment::instance()->getFilePath(
  	agxIO::Environment::RUNTIME_PATH );

  runtime_path.clear(); // Remove all previous settings
  runtime_path.pushbackPath( "MyPath/plugins" );

  // Try to find a file in the specified path
  std::string filename = runtime_path.find( "plugin.dll" );


Same procedure can be done for RESOURCE_PATH to specify in what directories images, models, scripts and other non-runtime resources should be searched for.

.. code-block:: c++

  // Get a file path container to where resource files are searched
  agx::FilePathContainer& resource_path =
    agxIO::Environment::instance()->getFilePath(
  	agxIO::Environment::RESOURCE_PATH );

  resource_path.clear(); // Remove all previous settings
  resource_path.pushbackPath( "MyPath/data/images;MyPath/data/models;" );
  resource_path.pushbackPath( "MyPath/data/textures" );

  // Try to find a file in the specified path
  std::string filename = resource_path.find( "heightfield.png" );

In the windows version ‘;’ should be used to separate paths, and under UNIX the ‘:’ letter is used. Paths can be absolute or relative.