FileFormatHandler Manual

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:

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
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)
{
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.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)
{
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

maxon::GetImageOf
ImageRef GetImageOf(const ImageBaseRef &bmp)
maxon::String
Definition: string.h:1197
maxon::OK
return OK
Definition: apibase.h:2485
iferr_return
#define iferr_return
Definition: resultbase.h:1434
maxon::Url::Set
Result< void > Set(KEY &&key, T &&data, Bool persistent=true)
Definition: url.h:906
MAXON_SOURCE_LOCATION
#define MAXON_SOURCE_LOCATION
Definition: memoryallocationbase.h:66
maxon::Float
Float64 Float
Definition: apibase.h:188
maxon::BaseArray
Definition: basearray.h:366
maxon::IOARCHIVEEXTRACTFLAGS
IOARCHIVEEXTRACTFLAGS
Extract Flags used in ReadArchiveInterface::Extract() and ReadArchiveInterface::ExtractSingleFile().
Definition: ioarchivehandler.h:32
maxon::Url
Definition: url.h:819
maxon::Result< void >
maxon::BaseArray::GetCount
MAXON_ATTRIBUTE_FORCE_INLINE Int GetCount() const
Definition: basearray.h:527
maxon::ThreadRefTemplate< ThreadInterface >
maxon::Int
Int64 Int
signed 32/64 bit int, size depends on the platform
Definition: apibase.h:179
iferr_scope
#define iferr_scope
Definition: resultbase.h:1343
maxon::IOARCHIVEEXTRACTFLAGS::OVERWRITE_EXISTING_FILE
@ OVERWRITE_EXISTING_FILE
Overwrites the file silently if it already exists in the directory.
maxon::TimeValue
The TimeValue class encapsulates a timer value.
Definition: timevalue.h:33
maxon::TimeValue::SetSeconds
void SetSeconds(Float64 seconds)
Definition: timevalue.h:232
maxon::BaseCollection< BaseArray< T, BASEARRAY_DEFAULT_CHUNK_SIZE, BASEARRAYFLAGS::NONE, DefaultAllocator >, BaseArrayData< T, DefaultAllocator, STD_IS_REPLACEMENT(empty, DefaultAllocator)> >::IsEmpty
MAXON_ATTRIBUTE_FORCE_INLINE Bool IsEmpty() const
Definition: collection.h:339
maxon::MEDIASESSIONFLAGS::NONE
@ NONE