/*===========================================================================
                    IMPORTANT NOTICE

            Not to be distributed in source format.

FILE:  bridle_Media.h

SERVICES:  Bridle'd IMedia. 

GENERAL DESCRIPTION:
   Contains inlined code that does swi-ing into OEM layer.	

        Copyright © 2003 QUALCOMM Incorporated.
               All Rights Reserved.
            QUALCOMM Proprietary/GTDR
===========================================================================*/

#ifndef BRIDLE_MEDIA_H
#define BRIDLE_MEDIA_H

#include "AEEMedia.h"
#include "AEEBridle.h"

/*===============================================================================

      BRIDLE SETUP

===============================================================================*/

/*===============================================================================

      Define packbridle Functions

===============================================================================*/
#define OEMMM_DEFINE_PACKBRIDLE_API(m) \
   \
   PACKBRIDLE_SUBSYS_2_RET(m, int, OEMMedia_New, \
                           AEECLSID, \
                           OEMINSTANCE *) \
    \
   PACKBRIDLE_SUBSYS_1_VOID(m, OEMMedia_Delete, \
                           OEMINSTANCE) \
    \
   PACKBRIDLE_SUBSYS_1_RET(m, int, OEMMedia_Start, \
                           OEMINSTANCE) \
    \
   PACKBRIDLE_SUBSYS_1_RET(m, int, OEMMedia_Stop, \
                           OEMINSTANCE) \
    \
   PACKBRIDLE_SUBSYS_2_RET(m, int, OEMMedia_PauseResume, \
                           OEMINSTANCE, \
                           boolean) \
    \
   PACKBRIDLE_SUBSYS_3_RET(m, int, OEMMedia_Seek, \
                           OEMINSTANCE, \
                           AEEMediaSeek, \
                           int32) \
    \
   PACKBRIDLE_SUBSYS_6_RET(m, int, OEMMedia_SetParm, \
                           OEMINSTANCE, \
                           uint16, \
                           uint32, \
                           uint32, \
                           uint32, \
                           boolean) \
    \
   PACKBRIDLE_SUBSYS_5_RET(m, int, OEMMedia_GetParm, \
                           OEMINSTANCE, \
                           uint16, \
                           uint32 *, \
                           uint32 *, \
                           uint32 *)

/*===============================================================================

      Define Function IDs

===============================================================================*/
#define OEMMM_DEFINE_BRIDLE_ENUM(m) \
   BRIDLE_SUBSYS_HANDLER_IDX(m, OEMMedia_New),\
   BRIDLE_SUBSYS_HANDLER_IDX(m, OEMMedia_Delete), \
   BRIDLE_SUBSYS_HANDLER_IDX(m, OEMMedia_Start), \
   BRIDLE_SUBSYS_HANDLER_IDX(m, OEMMedia_Stop), \
   BRIDLE_SUBSYS_HANDLER_IDX(m, OEMMedia_PauseResume), \
   BRIDLE_SUBSYS_HANDLER_IDX(m, OEMMedia_Seek), \
   BRIDLE_SUBSYS_HANDLER_IDX(m, OEMMedia_SetParm), \
   BRIDLE_SUBSYS_HANDLER_IDX(m, OEMMedia_GetParm), \
   BRIDLE_##m##_COUNT

/*===============================================================================

      Subsys Handler Table Entries

===============================================================================*/
#define OEMMM_DEFINE_BRIDLE_INIT_SYBSYS_HANDLER_TABLE(m) \
   BRIDLE_INIT_SUBSYS_HANDLER_TABLE(m, OEMMedia_New); \
   BRIDLE_INIT_SUBSYS_HANDLER_TABLE(m, OEMMedia_Delete); \
   BRIDLE_INIT_SUBSYS_HANDLER_TABLE(m, OEMMedia_Start); \
   BRIDLE_INIT_SUBSYS_HANDLER_TABLE(m, OEMMedia_Stop); \
   BRIDLE_INIT_SUBSYS_HANDLER_TABLE(m, OEMMedia_PauseResume); \
   BRIDLE_INIT_SUBSYS_HANDLER_TABLE(m, OEMMedia_Seek); \
   BRIDLE_INIT_SUBSYS_HANDLER_TABLE(m, OEMMedia_SetParm); \
   BRIDLE_INIT_SUBSYS_HANDLER_TABLE(m, OEMMedia_GetParm);


/*===============================================================================

      HELPER MACROS TO DECLARE OEMMedia API --
      STATIC unpackbridle_OEMMedia AND OEMMedia FUNCTIONS

===============================================================================*/
#define DECLARE_STATIC_UNPACKBRIDLE_OEMMEDIA_FUNCTIONS() \
   static uint32 unpackbridle_OEMMedia_New(uint32 swi, uint32 a1, uint32 a2, uint32 a3, uint32 a4); \
   static uint32 unpackbridle_OEMMedia_Delete(uint32 swi, uint32 a1, uint32 a2, uint32 a3, uint32 a4); \
   static uint32 unpackbridle_OEMMedia_Start(uint32 swi, uint32 a1, uint32 a2, uint32 a3, uint32 a4); \
   static uint32 unpackbridle_OEMMedia_Stop(uint32 swi, uint32 a1, uint32 a2, uint32 a3, uint32 a4); \
   static uint32 unpackbridle_OEMMedia_PauseResume(uint32 swi, uint32 a1, uint32 a2, uint32 a3, uint32 a4); \
   static uint32 unpackbridle_OEMMedia_Seek(uint32 swi, uint32 a1, uint32 a2, uint32 a3, uint32 a4); \
   static uint32 unpackbridle_OEMMedia_SetParm(uint32 swi, uint32 a1, uint32 a2, uint32 a3, uint32 a4); \
   static uint32 unpackbridle_OEMMedia_GetParm(uint32 swi, uint32 a1, uint32 a2, uint32 a3, uint32 a4);

#define DECLARE_STATIC_OEMMEDIA_FUNCTIONS() \
   static int  OEMMedia_New(AEECLSID cls, OEMINSTANCE * ph); \
   static void OEMMedia_Delete(OEMINSTANCE h); \
   static int  OEMMedia_Start(OEMINSTANCE h); \
   static int  OEMMedia_Stop(OEMINSTANCE h); \
   static int  OEMMedia_PauseResume(OEMINSTANCE h, boolean bPause); \
   static int  OEMMedia_Seek(OEMINSTANCE h, AEEMediaSeek eSeek, int32 lTimeMS); \
   static int  OEMMedia_SetParm(OEMINSTANCE h, int16 nParmID, int32 p1, int32 p2, int32 p3, boolean bLocal); \
   static int  OEMMedia_GetParm(OEMINSTANCE h, int16 nParmID, int32 * pP1, int32 * pP2, int32 * pP3);

/*===============================================================================

   OEMMedia API

===============================================================================*/
#define OEMMEDIA_New                            packbridle_OEMMedia_New
#define OEMMEDIA_Delete                         packbridle_OEMMedia_Delete
#define OEMMEDIA_Start                          packbridle_OEMMedia_Start
#define OEMMEDIA_Stop                           packbridle_OEMMedia_Stop
#define OEMMEDIA_Pause(h)                       packbridle_OEMMedia_PauseResume(h, TRUE)
#define OEMMEDIA_Resume(h)                      packbridle_OEMMedia_PauseResume(h, FALSE)
#define OEMMEDIA_Seek                           packbridle_OEMMedia_Seek
#define OEMMEDIA_SetParm(h, i, p1, p2, p3)      packbridle_OEMMedia_SetParm(h, i, p1, p2, p3, FALSE)
#define OEMMEDIA_SetParmLocal(h, i, p1, p2, p3) packbridle_OEMMedia_SetParm(h, i, p1, p2, p3, TRUE)
#define OEMMEDIA_GetParm                        packbridle_OEMMedia_GetParm

/*=======================================================================
  INTERFACES   DOCUMENTATION
=======================================================================

Interface Name: OEMMedia_Multimedia_Layer

Description:

IMedia implementation in OEM layer uses OEMMedia APIs defined in 
this file to interface with device multimedia layer to perform all 
the IMedia operations.

OEMMedia APIs help OEMs BRIDLElize IMedia implementations in OEM layer.
===H2>
How To Use Macros and APIs in this file to BRIDLElize IMedia implementation in OEM Layer
===/H2>

Let's assume, 
(1) You've implememted IMediaMPEG4 in OEMMediaMPEG4.c and you want to BRIDLElize it 
(2) The device multimedia API needed to perform IMediaMPEG4 operations is 
    FooMM API (Concrete example: QUALCOMM CMX API)
(3) IMediaMPEG4 code and data resides in user area
    FooMM code and data resides in supervisor area
    BRIDLE (unpackbridle) OEMMedia code and data resides in supervisor area

Follow these steps:
(1) Use "FooMM" as the module name in all the BRIDLE macros
(2) Create bridle_FooMM.h:
~
      (a) Include bridle_Media.h~
      (b) Use OEMMM_DEFINE_BRIDLE_ENUM() to define the IDs for each OEMMedia API:~
===pre>
            enum {
               OEMMM_DEFINE_BRIDLE_ENUM(FooMM)
            };
===/pre>
      (c) Call OEMMM_DEFINE_PACKBRIDLE_API(FooMM) to define packbridle OEMMedia APIs:~
      (d) Define parameters and data structures specific to FooMM. This enables 
          you to feed appropriate data via OEMMEDIA_SetParm() API to the 
          OEMMedia object implemented in bridle_FooMM.c~
*

(3) Create bridle_FooMM.c:
~
      (a) Call DECLARE_STATIC_UNPACKBRIDLE_OEMMEDIA_FUNCTIONS(FooMM) to declare static 
          OEMMedia unpackbridle functions that perform access check and call corresponding
          OEMMedia function~
      (b) Call DECLARE_STATIC_OEMMEDIA_FUNCTIONS(FooMM) to declare static OEMMedia functions
          that interface with FooMM to carry out the API functionality~
      (c) Define bridle_FooMM_RegisterSystem() function using OEMMM_DEFINE_BRIDLE_INIT_SYBSYS_HANDLER_TABLE()
          macro:~
===pre>
          int bridle_MediaCMX_RegisterSubSystem(void *po)
          {
            OEMMM_DEFINE_BRIDLE_INIT_SYBSYS_HANDLER_TABLE(FooMM);

            return BRIDLE_REGISTER_SUBSYS(FooMM);
          }
===/pre>

      (d) Implement static OEMMedia unpackbridle functions and perform access checks~
      (e) Implement static OEMMedia functions and call relevant FooMM APIs to carry out the
          API functionality~
*

(4) Use OEMMEDIA_XXX() APIs in OEMMediaMPEG4.c
      
List of Header files to be included:~
bridle_Media.h

=============================================================================

OEMMEDIA_New()

Description:
   This function creates the OEMMedia object that is refered by IMedia object.

Prototype:
   int OEMMEDIA_New(AEECLSID cls, OEMINSTANCE * ph);

Parameters:
   cls: Class ID
   ph [out]: Pointer to the instance handle of the allocated object
 
Return Value:
   SUCCESS if successful
   Error code if error

Comments:
   None.

See Also:
   OEMMEDIA_Delete()

=============================================================================

OEMMEDIA_Delete()

Description:
   This function deletes the OEMMedia object.

Prototype:
   void OEMMEDIA_Delete(OEMINSTANCE h);

Parameters:
   h: Instance handle
 
Return Value:
   SUCCESS if successful
   Error code if error

Comments:
   OEM camera object must be deleted.

See Also:
   OEMMEDIA_Delete()

=============================================================================

OEMMEDIA_Start()

Description:
   This function starts media operation like playback or recording.

Prototype:
   int OEMMEDIA_Start(OEMINSTANCE h);

Parameters:
   h: Instance handle
 
Return Value:
   SUCCESS: Command accepted
   Error code if error

Comments:
   None.

See Also:
   OEMMEDIA_Stop()
   OEMMEDIA_Pause()

=============================================================================

OEMMEDIA_Stop()

Description:
   This function stops the media operation like playback or recording.

Prototype:
   int OEMMEDIA_Stop(OEMINSTANCE h);

Parameters:
   h: Instance handle
 
Return Value:
   SUCCESS: Command accepted
   Error code if error

Comments:
   None.

See Also:
   OEMMEDIA_Start()

=============================================================================

OEMMEDIA_Pause()

Description:
   This function pauses the current media operation.

Prototype:
   int OEMMEDIA_Pause(OEMINSTANCE h, boolean bPause);

Parameters:
   h: Instance handle
 
Return Value:
   SUCCESS: Command accepted
   Error code if error

Comments:
   None

See Also:
   OEMMEDIA_Start()

=============================================================================

OEMMEDIA_Resume()

Description:
   This function resume the current media operation.

Prototype:
   int OEMMEDIA_Pause(OEMINSTANCE h, boolean bPause);

Parameters:
   h: Instance handle
 
Return Value:
   SUCCESS: Command accepted
   Error code if error

Comments:
   None

See Also:
   OEMMEDIA_Start()

=============================================================================

OEMMEDIA_Seek()

Description:
   This function resume the current media operation.

Prototype:
   int OEMMEDIA_Seek(OEMINSTANCE h, AEEMediaSeek eSeek, lTimeMS);

Parameters:
   h: Instance handle
   eSeek: Seek reference
   lTimeMS: Time in milliseconds. Negative value indicates reverse direction.
 
Return Value:
   SUCCESS: Command accepted
   Error code if error

Comments:
   None

See Also:
   OEMMEDIA_Start()

=============================================================================

OEMMEDIA_SetParm()

Description:
   This function sets the OEMMedia specific parameters. The settings may issue
   device multimedia API calls to carry out the operation.

Prototype:
   int OEMMEDIA_SetParm(OEMINSTANCE h, int16 nParmID, int32 p1, int32 p2, int32 p3);

Parameters:
   h: Instance handle
   nParmID: CAM_PARM_XXX
   p1: Depends on parameter
   p2: Depends on parameter
   p3: Depends on parameter
 
Return Value:
   SUCCESS:    Successful. Operation is completed.
   Error code if error

Comments:
   The parameters are dependent on the specific device multimedia layer API.

See Also:
   OEMMEDIA_SetParmLocal()
   OEMMEDIA_GetParm()

=============================================================================

OEMMEDIA_SetParmLocal()

Description:
   This function sets the OEMMedia specific parameters. The setting happens
   locally in OEMMedia object and device multimedia API is not called.

Prototype:
   int OEMMEDIA_SetParmLocal(OEMINSTANCE h, int16 nParmID, int32 p1, int32 p2, int32 p3);

Parameters:
   h: Instance handle
   nParmID: CAM_PARM_XXX
   p1: Depends on parameter
   p2: Depends on parameter
   p3: Depends on parameter
 
Return Value:
   SUCCESS:    Successful. Operation is completed.
   Error code if error

Comments:
   The parameters are dependent on the specific device multimedia layer API.

See Also:
   OEMMEDIA_SetParm()
   OEMMEDIA_GetParm()

=============================================================================

OEMMEDIA_GetParm()

Description:
   This function gets the OEMMedia specific parameters. The settings may issue
   device multimedia API calls to carry out the operation.

Prototype:
   int OEMMEDIA_GetParm(OEMINSTANCE h, int16 nParmID, int32 * pP1, int32 * pP2, int32 * pP3);

Parameters:
   h: Instance handle
   nParmID: CAM_PARM_XXX
   pP1: Depends on parameter
   pP2: Depends on parameter
   pP3: Depends on parameter
 
Return Value:
   SUCCESS:    Successful. Operation is completed.
   Error code if error

Comments:
   The parameters are dependent on the specific device multimedia layer API.

See Also:
   OEMMEDIA_SetParm()
   OEMMEDIA_SetParmLocal()

=============================================================================*/

#endif // BRIDLE_MEDIA_H
