FileFormatHandler Manual

Table of Contents

• About
• FileFormatHandlerInterface
• Registered Handlers
• Further Reading

About

The maxon::FileFormatHandlerInterface provides functionality to access files of a given type. It is typically used to create specific handlers using CreateHandler().

FileFormatHandlerInterface

The FileFormatHandler for a given file is typically obtained with maxon::FileFormatDetectionInterface::Detect().

The maxon::FileFormatHandlerInterface provides these functions:

• maxon::FileFormatHandlerInterface::GetFileFormat(): Returns the file format. See maxon::FileFormats.
• maxon::FileFormatHandlerInterface::GetHandlerType(): Returns the data type of the reference class of the handler returned by CreateHandler().
• maxon::FileFormatHandlerInterface::CreateHandler(): Creates the handler to access the given file e.g. MediaInputRef, ReadArchiveRef, IoBrowseRef etc.

Registered Handlers

The following maxon::FileFormatHandler implementations are registered at the maxon::FileFormatHandlers registry and are accessible at these published objects:

• maxon::FileFormatHandlers::GenericFile: Returns no handler because it indicates just a regular file
• maxon::FileFormatHandlers::Browsable: Returns maxon::IoBrowseRef for directories.
• maxon::FileFormatHandlers::MaxonDocumentBinaryHandler: Returns maxon::DataFormatReaderRef.
• maxon::FileFormatHandlers::MaxonDocumentJsonHandler: Returns maxon::DataFormatReaderRef.
• maxon::FileFormatHandlers::MaxonDocumentXmlHandler: Returns maxon::DataFormatReaderRef.

Archive files. See also Archives Manual.

• maxon::FileFormatHandlers::ZipDirectoryBrowser: Returns maxon::IoBrowseRef for directories.
• maxon::FileFormatHandlers::ZipArchiveHandler: Returns maxon::ReadArchiveRef for directories.
• maxon::FileFormatHandlers::GZipDirectoryBrowser: Returns maxon::IoBrowseRef for directories.

  // This example extracts all files from the given ZIP file into a target folder.
 
  // create ReadArchiveRef handler for a ZIP file
  const maxon::FileFormatHandler& handler = maxon::FileFormatHandlers::ZipArchiveHandler();
  const maxon::ReadArchiveRef     zipArchive = handler.CreateHandler<maxon::ReadArchiveRef>(maxon::Url()) iferr_return;
 
  // open ZIP file
  zipArchive.Open(zipFile) iferr_return;
 
  // extract all files to the given target folder
  const maxon::IOARCHIVEEXTRACTFLAGS flags = maxon::IOARCHIVEEXTRACTFLAGS::OVERWRITE_EXISTING_FILE;
  zipArchive.Extract(targetFolder, maxon::ThreadRef(), flags, nullptr) iferr_return;
 
  // close ZIP file
  zipArchive.Close() iferr_return;

These handlers access image and video files and return a maxon::MediaInputRef. See Images Manual and Media Sessions Manual.

• maxon::FileFormatHandlers::ImageLoaderJpg
• maxon::FileFormatHandlers::ImageLoaderBmp
• maxon::FileFormatHandlers::ImageLoaderIff
• maxon::FileFormatHandlers::ImageLoaderIco
• maxon::FileFormatHandlers::ImageLoaderPng
• maxon::FileFormatHandlers::ImageLoaderTiff
• maxon::FileFormatHandlers::ImageLoaderHdr
• maxon::FileFormatHandlers::ImageLoaderPict
• maxon::FileFormatHandlers::ImageLoaderPsd
• maxon::FileFormatHandlers::ImageLoaderPsb
• maxon::FileFormatHandlers::MovieImageSequence
• maxon::FileFormatHandlers::MovieWinMF
• maxon::FileFormatHandlers::AudioWinMF

Audio files are handled with these handler which also return a maxon::MediaInputRef:

• maxon::FileFormatHandlers::AudioLoaderWav
• maxon::FileFormatHandlers::AudioLoaderAiff

// This example function loads the image data from the image file at the
// given URL. The image data is loaded into the given ImageTextureRef.
// For convenience one can also use maxon::ImageTextureRef::Load() or maxon::MediaSessionImport().
 
//----------------------------------------------------------------------------------------
// Loads the image at the given URL.
// @param[in] url               The URL of the image file.
// @param[out] targetTexture    The ImageTextureRef to load the image into.
// @return                      OK on success.
//----------------------------------------------------------------------------------------
static maxon::Result<void> LoadImageFromUrl(const maxon::Url& url, maxon::ImageTextureRef& targetTexture)
{
  iferr_scope;
 
  if (url.IsEmpty())
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  // define source
 
  const maxon::FileFormatHandler importFileFormat = maxon::FileFormatDetectionInterface::Detect<maxon::MediaInputRef>(url) iferr_return;
  const maxon::MediaInputRef     source = importFileFormat.CreateHandler<maxon::MediaInputRef>(url) iferr_return;
 
  // define destination
 
  const maxon::MediaOutputTextureRef destination = maxon::MediaOutputTextureClass().Create() iferr_return;
  destination.SetOutputTexture(targetTexture, maxon::ImagePixelStorageClasses::Normal()) iferr_return;
 
  // convert
 
  const maxon::MediaSessionRef session = maxon::MediaSessionObject().Create() iferr_return;
  session.ConnectMediaConverter(source, destination) iferr_return;
 
  session.Convert(maxon::TimeValue(), maxon::MEDIASESSIONFLAGS::NONE) iferr_return;
  session.Close() iferr_return;
 
  return maxon::OK;
}

// This example function loads an image sequence found in the given folder.
// The images are loaded in the prepared ImageRef array.
 
//----------------------------------------------------------------------------------------
// Loads the image sequence found in the given folder.
// @param[in] folder            Folder containing an image sequence in the format "sequence_00.png".
// @param[out] images           Array with pre-allocated images to load the image data into.
// @return                      OK on success.
//----------------------------------------------------------------------------------------
static maxon::Result<void> LoadImageSequence(const maxon::Url& folder, maxon::BaseArray<maxon::ImageRef>& images)
{
  iferr_scope;
 
  if (folder.IsEmpty() || images.IsEmpty())
    return maxon::IllegalArgumentError(MAXON_SOURCE_LOCATION);
 
  // load only as many images as the ImageRef array can hold
  const maxon::Int   firstFrame = 0;
  const maxon::Int   lastFrame  = images.GetCount() - 1;
  const maxon::Float fps = 25.0_f;
 
  // define source
 
  const maxon::String filename { "sequence_" };
  maxon::Url sequenceURL = (folder + maxon::Url(filename))iferr_return;
 
  maxon::String name = sequenceURL.GetName();
  // between "{" and "}" the number format is defined as used with FormatString().
  // the file name format is sequence_00.png, sequence_01.png, ...
  name += "@{2'0'}.png"_s;
  sequenceURL.SetName(name) iferr_return;
 
  sequenceURL.Set(maxon::URLFLAGS::IMAGESEQUENCE_FPS, fps) iferr_return;
  sequenceURL.Set(maxon::URLFLAGS::IMAGESEQUENCE_FIRSTFRAME, firstFrame) iferr_return;
  sequenceURL.Set(maxon::URLFLAGS::IMAGESEQUENCE_LASTFRAME, lastFrame) iferr_return;
 
  const maxon::FileFormatHandler imageSequence = maxon::FileFormatHandlers::MovieImageSequence();
  const maxon::MediaInputRef     source = imageSequence.CreateHandler<maxon::MediaInputRef>(sequenceURL) iferr_return;
 
  // define destination
 
  const maxon::ImageTextureRef       texture = maxon::ImageTextureClasses::TEXTURE().Create() iferr_return;
  const maxon::MediaOutputTextureRef destination = maxon::MediaOutputTextureClass().Create() iferr_return;
  destination.SetOutputTexture(texture, maxon::ImagePixelStorageClasses::Normal()) iferr_return;
 
  // convert
 
  const maxon::MediaSessionRef session = maxon::MediaSessionObject().Create() iferr_return;
  session.ConnectMediaConverter(source, destination) iferr_return;
 
  // fps
  maxon::TimeValue frameDuration;
  frameDuration.SetSeconds(1.0 / fps);
  maxon::TimeValue currentTime;
 
  // load each frame
  for (maxon::Int frame = 0; frame <= lastFrame; ++frame)
  {
    // load frame
    session.Convert(currentTime, maxon::MEDIASESSIONFLAGS::NONE) iferr_return;
    // get image
    const maxon::ImageRef image = maxon::GetImageOf(texture);
    // copy image to target array
    images[frame] = image.Clone() iferr_return;
 
    currentTime += frameDuration;
  }
 
  return session.Close();
}

Further Reading

• Files & Media
• MAXON API Files & Media
• Url Manual
• Archives Manual
• Media Sessions Manual