DM_PictureReaderHandler

3.50 DM_PictureReaderHandler

This function is used to register and manage custom graphics handlers (GFX handlers) with the IDM. These handlers are invoked by the IDM to load images specified at tile resources or image objects.

Custom graphics handlers are described in DM_PictureHandler.

DM_Boolean DML_default DM_EXPORT DM_PictureReaderHandler
(
  DM_PictureReaderProc  funcp,
  DM_UInt  operation,
  DM_UInt  options
)

Parameters

-> DM_PictureReaderProc funcp

Pointer to a graphics handler for which the action defined in operation shall be performed.

The handler must be of this format:

DM_Boolean DML_default DM_CALLBACK <ProcName>
(
  DM_PicInfo * pic
)
{
  /* custom code */
}

Accordingly, the data type DM_PictureReaderProc is defined like this:

typedef DM_Boolean (DML_default DM_CALLBACK * DM_PictureReaderProc) __((DM_PicInfo * pic));

-> DM_UInt operation

This parameter defines which action shall be performed for the graphics handler.

Value range

DMF_RegisterHandler

Registers the handler with the IDM.
DMF_WithdrawHandler

Unregisters the handler with the IDM.
DMF_EnableHandler

Activates the handler.
DMF_DisableHandler

Deactivates the handler.

After a handler is registered, it is activated automatically. More than one graphics handler may be registered, but each handler only once.

-> DM_UInt options

Currently unused; has to be 0.

Return value

DM_TRUE	The action was completed successfully.
DM_FALSE	In case of an error.

Remarks

The registered graphics handlers are invoked in reverse order as they were registered.

Because graphics handlers allocate memory when loading images, a handler must not be disabled or unregistered until the memory it has allocated is freed by itself or another graphics handler. If all graphics handlers allocate their memory in the same way, a graphics handler can free the memory that has been allocated by other handlers. In that case, the first invoked graphics handler frees the memory, regardless of which handler previously allocated it. Then it is sufficient for one graphics handler to remain registered and active in order to free the memory allocated by graphics handlers.

It is not necessary to unregister graphics handlers when exiting an application.