RetroArch/driver.h

/*  RetroArch - A frontend for libretro.
 *  Copyright (C) 2010-2014 - Hans-Kristian Arntzen
 *  Copyright (C) 2011-2017 - Daniel De Matteis
 *
 *  RetroArch is free software: you can redistribute it and/or modify it under the terms
 *  of the GNU General Public License as published by the Free Software Found-
 *  ation, either version 3 of the License, or (at your option) any later version.
 *
 *  RetroArch is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
 *  without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
 *  PURPOSE.  See the GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License along with RetroArch.
 *  If not, see <http://www.gnu.org/licenses/>.
 */

#ifndef __RARCH_DRIVER__H
#define __RARCH_DRIVER__H

#include <stdint.h>
#include <stdlib.h>
#include <sys/types.h>

#include <boolean.h>
#include <retro_common_api.h>

#include "configuration.h"
#include "retroarch_types.h"

RETRO_BEGIN_DECLS

/* Bit positions for the driver masks below.  These are shift counts,
 * not masks: the only valid use is as the right-hand operand of a
 * shift.  The DRIVER_BIT_ prefix exists to stop them being mistaken
 * for masks in a `flags & X` test, which compiles silently and picks
 * out whichever unrelated drivers happen to share bits with the
 * position's numeric value. */
enum
{
   DRIVER_BIT_AUDIO = 0,
   DRIVER_BIT_VIDEO,
   DRIVER_BIT_INPUT,
   DRIVER_BIT_CAMERA,
   DRIVER_BIT_LOCATION,
   DRIVER_BIT_MENU,
   DRIVER_BIT_BLUETOOTH,
   DRIVER_BIT_WIFI,
   DRIVER_BIT_LED,
   DRIVER_BIT_MIDI,
   DRIVER_BIT_MICROPHONE
};

enum
{
   DRIVER_AUDIO_MASK        = 1 << DRIVER_BIT_AUDIO,
   DRIVER_VIDEO_MASK        = 1 << DRIVER_BIT_VIDEO,
   DRIVER_INPUT_MASK        = 1 << DRIVER_BIT_INPUT,
   DRIVER_CAMERA_MASK       = 1 << DRIVER_BIT_CAMERA,
   DRIVER_LOCATION_MASK     = 1 << DRIVER_BIT_LOCATION,
   DRIVER_MENU_MASK         = 1 << DRIVER_BIT_MENU,
   DRIVER_BLUETOOTH_MASK    = 1 << DRIVER_BIT_BLUETOOTH,
   DRIVER_WIFI_MASK         = 1 << DRIVER_BIT_WIFI,
   DRIVER_LED_MASK          = 1 << DRIVER_BIT_LED,
   DRIVER_MIDI_MASK         = 1 << DRIVER_BIT_MIDI,
   DRIVER_MICROPHONE_MASK   = 1 << DRIVER_BIT_MICROPHONE
};

/* Video and input are a single unit: input is initialised inside
 * video_driver_init_internal(), and several video drivers hand back
 * the input driver and its data through their init() out-params.
 * Neither can be reinitialised without the other, so requests naming
 * one are widened to both. */
#define DRIVER_VIDEO_AND_INPUT_MASK (DRIVER_VIDEO_MASK | DRIVER_INPUT_MASK)

#define DRIVER_FLAGS_NORMALIZE(flags) \
   do \
   { \
      if ((flags) & DRIVER_VIDEO_AND_INPUT_MASK) \
         (flags) |= DRIVER_VIDEO_AND_INPUT_MASK; \
   } while (0)

/**
 * These flags indicate special requirements or requests
 * of a driver's setup or teardown process.
 *
 * They are passed to \c drivers_init and \c driver_deinit.
 * Not all drivers will need them.
 *
 * @see drivers_init
 * @see driver_deinit
 */
enum driver_lifetime_flags
{
   /**
    * Indicates that the driver is being reset.
    * When passed \c driver_deinit, indicates that the targeted drivers
    * are about to be reinitialized.
    * When passed to \c driver_init, indicates that the targeted drivers
    * are in the middle of being reinitialized.
    *
    * This is useful for drivers that provide core-accessible resource handles,
    * such as the microphone driver.
    * When closed by normal means, such drivers will de-allocate the resources
    * that their opened handles represent.
    * If the game isn't being exited, then these resources would effectively
    * be closed while the core might still be using them.
    *
    * This flag can be used to ensure that existing core-accessible handles
    * are reinitialized with valid resources
    * before the core notices that anything's wrong.
    */
   DRIVER_LIFETIME_RESET = 1 << 0,

   /**
    * Passed to \c driver_uninit when the drivers are freed to be
    * started again at once for another session: content loaded or
    * closed, one core for another. It is not a reset - what a core's
    * unloading ends still ends - but a driver that can outlive the
    * video driver may be left running across it, as across a reset.
    */
   DRIVER_LIFETIME_SESSION_SWITCH = 1 << 1,

   /**
    * Passed to \c drivers_init along a content switch that left the
    * audio driver out of the teardown: the running audio is carried
    * into the new session - its rate set in place once the video
    * driver has settled the rates - instead of opened again.
    */
   DRIVER_LIFETIME_AUDIO_CARRIED = 1 << 2
};

enum driver_ctl_state
{
   RARCH_DRIVER_CTL_NONE = 0,

   /* Sets monitor refresh rate to new value by calling
    * video_monitor_set_refresh_rate(). Subsequently
    * calls audio_monitor_set_refresh_rate(). */
   RARCH_DRIVER_CTL_SET_REFRESH_RATE,

   RARCH_DRIVER_CTL_FIND_FIRST,

   RARCH_DRIVER_CTL_FIND_LAST,

   RARCH_DRIVER_CTL_FIND_PREV,

   RARCH_DRIVER_CTL_FIND_NEXT
};

typedef struct driver_ctx_info
{
   const char *label;
   char *s;
   ssize_t len;
} driver_ctx_info_t;

bool driver_ctl(enum driver_ctl_state state, void *data);

/**
 * driver_find_index:
 * @label              : string of driver type to be found.
 * @drv                : identifier of driver to be found.
 *
 * Find index of the driver, based on @label.
 *
 * Returns: -1 if no driver based on @label and @drv found, otherwise
 * index number of the driver found in the array.
 **/
int driver_find_index(const char *label, const char *drv);

/* Sets audio and video drivers to nonblock state.
 *
 * If nonblock state is false, sets blocking state for both
 * audio and video drivers instead. */
void driver_set_nonblock_state(void);

/* Carries a new core audio rate to the running audio driver, keeping the
 * device open. Returns false when the drivers need the reinit for it. */
bool driver_set_audio_input_rate(void);

/**
 * drivers_init:
 * @flags              : Bitmask of drivers to initialize.
 *
 * Initializes drivers.
 * @flags determines which drivers get initialized.
 **/
void drivers_init(settings_t *settings, int flags,
      enum driver_lifetime_flags lifetime_flags, bool verbosity_enabled);

/**
 * Driver ownership - set this to true if the platform in
 * question needs to 'own'
 * the respective handle and therefore skip regular RetroArch
 * driver teardown/reiniting procedure.
 *
 * If  to true, the 'free' function will get skipped. It is
 * then up to the driver implementation to properly handle
 * 'reiniting' inside the 'init' function and make sure it
 * returns the existing handle instead of allocating and
 * returning a pointer to a new handle.
 *
 * Typically, if a driver intends to make use of this, it should
 * set this to true at the end of its 'init' function.
 **/
void driver_uninit(int flags, enum driver_lifetime_flags lifetime_flags);

void retro_input_poll_null(void);

RETRO_END_DECLS

#endif