text: /*############################################################################
    # Copyright (C) 2017-2020 Intel Corporation
    #
    # SPDX-License-Identifier: MIT
    ############################################################################*/
  
  #ifndef __MFXSESSION_H__
  #define __MFXSESSION_H__
  #include "mfxcommon.h"
  
  #ifdef __cplusplus
  extern "C"
  {
  #endif /* __cplusplus */
  
  /* Global Functions */
  
  /*! Session handle. */
  typedef struct _mfxSession *mfxSession;
  
  /*!
     @brief
        Creates and initializes a session in the Legacy mode.
  
        Call this function before calling
        any other API function. If the desired implementation specified by ``impl`` is MFX_IMPL_AUTO,
        the function will search for the platform-specific implementation.
        If the function cannot find the platform-specific implementation, it will use the software implementation instead.
  
        The ``ver`` argument indicates the desired version of the library implementation.
        The loaded implementation will have an API version compatible to the specified version (equal in
        the major version number, and no less in the minor version number.) If the desired version
        is not specified, the default is to use the API version from the library release with
        which an application is built.
  
        Production applications should always specify the minimum API version that meets the
        functional requirements. For example, if an application uses only H.264 decoding as described
        in API v1.0, the application should initialize the library with API v1.0. This ensures
        backward compatibility.
  
     @param[in] impl     mfxIMPL enumerator that indicates the desired legacy Intel(r) Media SDK implementation.
     @param[in] ver      Pointer to the minimum library version or zero, if not specified.
     @param[out] session Pointer to the legacy Intel(r) Media SDK session handle.
  
     @return
        MFX_ERR_NONE        The function completed successfully. The output parameter contains the handle of the session.\n
        MFX_ERR_UNSUPPORTED The function cannot find the desired legacy Intel(r) Media SDK implementation or version.
  */
  mfxStatus MFX_CDECL MFXInit(mfxIMPL impl, mfxVersion *ver, mfxSession *session);
  
  /*!
     @brief
        Creates and initializes a session.
  
        Call this function before calling any other API functions.
        If the desired implementation specified by ``par`` is MFX_IMPL_AUTO, the function will search for
        the platform-specific implementation. If the function cannot find the platform-specific implementation, it will use the software implementation instead.
  
        The argument ``par.Version`` indicates the desired version of the implementation. The loaded implementation will have an API
        version compatible to the specified version (equal in the major version number, and no less in the minor version number.)
        If the desired version is not specified, the default is to use the API version from the library release with
        which an application is built.
  
        Production applications should always specify the minimum API version that meets the functional requirements.
        For example, if an application uses only H.264 decoding as described in API v1.0, the application should initialize the library with API v1.0. This ensures backward compatibility.
  
        The argument ``par.ExternalThreads`` specifies threading mode. Value 0 means that the implementation should create and
        handle work threads internally (this is essentially the equivalent of the regular MFXInit). I
  
     @param[in]  par     mfxInitParam structure that indicates the desired implementation, minimum library version and desired threading mode.
     @param[out] session Pointer to the session handle.
  
     @return
        MFX_ERR_NONE        The function completed successfully. The output parameter contains the handle of the session.\n
        MFX_ERR_UNSUPPORTED The function cannot find the desired implementation or version.
  */
  mfxStatus MFX_CDECL MFXInitEx(mfxInitParam par, mfxSession *session);
  
  /*!
     @brief Completes and deinitializes a session. Any active tasks in execution or
      in queue are aborted. The application cannot call any API function after calling this function.
  
     All child sessions must be disjoined before closing a parent session.
     @param[in] session session handle.
  
     @return MFX_ERR_NONE The function completed successfully.
  */
  mfxStatus MFX_CDECL MFXClose(mfxSession session);
  
  /*!
     @brief Returns the implementation type of a given session.
  
     @param[in]  session Session handle.
     @param[out] impl    Pointer to the implementation type
  
     @return MFX_ERR_NONE The function completed successfully.
  */
  mfxStatus MFX_CDECL MFXQueryIMPL(mfxSession session, mfxIMPL *impl);
  
  /*!
     @brief Returns the implementation version.
  
     @param[in]  session Session handle.
     @param[out] version Pointer to the returned implementation version.
  
     @return MFX_ERR_NONE The function completed successfully.
  */
  mfxStatus MFX_CDECL MFXQueryVersion(mfxSession session, mfxVersion *version);
  
  /*!
     @brief Joins the child session to the current session.
  
     After joining, the two sessions share thread and resource scheduling for asynchronous
     operations. However, each session still maintains its own device manager and buffer/frame
     allocator. Therefore, the application must use a compatible device manager and buffer/frame
     allocator to share data between two joined sessions.
  
     The application can join multiple sessions by calling this function multiple times. When joining
     the first two sessions, the current session becomes the parent responsible for thread and
     resource scheduling of any later joined sessions.
  
     Joining of two parent sessions is not supported.
  
     @param[in,out] session    The current session handle.
     @param[in]     child      The child session handle to be joined
  
     @return MFX_ERR_NONE         The function completed successfully. \n
             MFX_WRN_IN_EXECUTION Active tasks are executing or in queue in one of the
                                  sessions. Call this function again after all tasks are completed. \n
             MFX_ERR_UNSUPPORTED  The child session cannot be joined with the current session.
  */
  mfxStatus MFX_CDECL MFXJoinSession(mfxSession session, mfxSession child);
  
  /*!
     @brief Removes the joined state of the current session.
  
            After disjoining, the current session becomes independent. The application must ensure there is no active task running in the session before calling this API function.
  
     @param[in,out] session    The current session handle.
  
     @return MFX_ERR_NONE                The function completed successfully. \n
             MFX_WRN_IN_EXECUTION        Active tasks are executing or in queue in one of the
                                         sessions. Call this function again after all tasks are completed. \n
             MFX_ERR_UNDEFINED_BEHAVIOR  The session is independent, or this session is the parent of all joined sessions.
  */
  mfxStatus MFX_CDECL MFXDisjoinSession(mfxSession session);
  
  /*!
     @brief Creates a clean copy of the current session.
  
            The cloned session is an independent session and does not inherit any user-defined buffer, frame allocator, or device manager handles from the current session.
            This function is a light-weight equivalent of MFXJoinSession after MFXInit.
  
     @param[in] session    The current session handle.
     @param[out] clone     Pointer to the cloned session handle.
  
     @return MFX_ERR_NONE                The function completed successfully.
  */
  mfxStatus MFX_CDECL MFXCloneSession(mfxSession session, mfxSession *clone);
  
  /*!
     @brief Sets the current session priority.
  
     @param[in] session    The current session handle.
     @param[in] priority   Priority value.
  
     @return MFX_ERR_NONE                The function completed successfully.
  */
  mfxStatus MFX_CDECL MFXSetPriority(mfxSession session, mfxPriority priority);
  
  /*!
     @brief Returns the current session priority.
  
     @param[in] session    The current session handle.
     @param[out] priority   Pointer to the priority value.
  
     @return MFX_ERR_NONE                The function completed successfully.
  */
  mfxStatus MFX_CDECL MFXGetPriority(mfxSession session, mfxPriority *priority);
  
  #ifdef __cplusplus
  }
  #endif /* __cplusplus */
  
  #endif
  
  