# PM123 Output Plug-ins

Decoder plug-ins must implement and export the functions defined in output_plug.h.

         ULONG DLLENTRY output_init  ( void **a )
         ULONG DLLENTRY output_uninit( void  *a )

- a : Allocate any chunk of memory necessary for the output's function. This pointer will be passed to the other functions.
- return value : PLUGIN_OK (0) means the output was initialized successfully.

Init function is called when the user requests the use of your output plug-in. So only one output plug-in is active at any given time. It should initialize the control variables for an eventual call to OUTPUT_OPEN. decoder_uninit is called when another output plug-in is request by the user and should free the allocated memory for a.

         ULONG DLLENTRY output_command( void *a, ULONG msg, OUTPUT_PARAMS *info )

- msg: one of the following:
  - OUTPUT_OPEN opens the device or file needed for output.
  - OUTPUT_CLOSE closes it.
  - OUTPUT_VOLUME changes the volume of an output device.
  - OUTPUT_PAUSE pauses the playback (ie.: block in output_playsamples()).
  - OUTPUT_SETUP setup the format that output_playsamples() will most likely receive, boost priority values, error_display functions and hwnd.
  - OUTPUT_TRASH_BUFFERS trash any buffers currently awating to be played.
- info: structure that contains the parameters needed by the preceding commands
- return value:
  PLUGIN_OK (0) -> ok.
  others -> MMOS/2 errors or anything else.

There is a lot of commands to implement for this function. Parameters needed for each of them are described in the definition of the structure in the .h file.

The output plug-in MUST WinPostMsg() the following messages to hwnd:

- WM_PLAYERROR when a playback error occures.
- WM_OUTPUT_OUTOFDATA when the output plug-in has finished playing all. its buffers. Not needed when `always_hungry` flag is enabled.

         ULONG DLLENTRY output_playing_samples( void* a, FORMAT_INFO* info,
                                                char* buf, int len )

- info - return the format of buf.
- buf - return len amount of data currently being played.
- len - requested amount of data to be placed in buf.
- return value:
  PLUGIN_OK (0) -> ok.
  PLUGIN_FAILED (-1) -> the data is not available or error occured.

This function is used by visual plug-ins so the user can visualize what is currently being played. len is usually not so big, so check that amount usually required by your visual plug-ins before making complicated buffering functions in your output plug-in.

         int DLLENTRY output_play_samples( void* a, FORMAT_INFO* format,
                                           char* buf,int len, int posmarker )

- format - format of buf.
- buf - data to play.
- len - length of buf.
- posmarker = position marker to return with output_playing_pos.
- return value: the number of bytes from len processed. ie.: < len = error.

This function is called by the decoder or last in chain filter plug-in to play samples.

         ULONG DLLENTRY output_playing_pos( void* a )

This function returns the posmarker from the buffer that the user currently hears.

         BOOL  DLLENTRY output_playing_data( void* a )

Returns TRUE if the output plug-in still has some buffers to play.