cin_driver.h

   1 /*
   2  * Copyright (c) 2018 AlaskanEmily
   3  * This Source Code Form is subject to the terms of the Mozilla Public
   4  * License, v. 2.0. If a copy of the MPL was not distributed with this
   5  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
   6  */
   7
   8 #ifndef CIN_DRIVER_H
   9 #define CIN_DRIVER_H
  10 #pragma once
  11
  12 #include "cin_export.h"
  13 #include "cin_format.h"
  14
  15 #ifdef __cplusplus
  16 extern "C" {
  17 #endif
  18
  19
  20 struct Cin_Loader;
  21 struct Cin_Sound;
  22
  23 /**
  24  * @defgroup Driver Functions that create, destroy, and manipulate the Driver.
  25  * @{
  26  */
  27
  28 struct Cin_Driver;
  29
  30 /**
  31  * @brief Errors that occur when creating or manipulating a Driver.
  32  */
  33 enum Cin_DriverError {
  34     Cin_eDriverSuccess, /**< No error occured */
  35     Cin_eDriverFailure,
  36     Cin_eDriverUnsupportedFormat, /**< The specified format is not supported */
  37     Cin_eDriverInvalidFormat, /**< The specified format is invalid */
  38     Cin_eDriverUnsupportedNumChannels, /**< Unsupported number of channels */
  39     Cin_eDriverUnsupportedSampleRate, /**< Unsupported sample rate */
  40     Cin_eDriverNoDevice
  41 };
  42
  43 /**
  44  * @brief Returns the size of struct Cin_Driver
  45  *
  46  * The client is expected to allocate space for the driver.
  47  */
  48 CIN_EXPORT(unsigned) Cin_StructDriverSize(void);
  49
  50 /**
  51  * @brief Initializes a Driver.
  52  *
  53  * The client is expected to allocate space for the driver. Use
  54  * Cin_StructDriverSize to get the size of the driver struct.
  55  *
  56  * @warning The data that is placed in drv must NOT be copied. Do not use
  57  *   memcpy on @p sdrv, other structures may depend on the address of @p drv.
  58  *
  59  * @sa Cin_StructDriverSize
  60  * @sa Cin_DestroyDriver
  61  * @todo There is currently no way to enumerate devices.
  62  */
  63 CIN_EXPORT(enum Cin_DriverError) Cin_CreateDriver(struct Cin_Driver *drv);
  64
  65 /**
  66  * @brief Destroys the Driver
  67  *
  68  * As the storage space for @p drv was allocated by the client, they must also
  69  * free the space after use.
  70  */
  71 CIN_EXPORT(void) Cin_DestroyDriver(struct Cin_Driver *drv);
  72
  73 /**
  74  * @brief Returns if the Driver supports creating loaders for a format.
  75  */
  76 CIN_EXPORT(enum Cin_DriverError) Cin_DriverSupportsFormat(
  77     const struct Cin_Driver *drv,
  78     enum Cin_Format format,
  79     unsigned num_channels);
  80
  81 CIN_EXPORT(enum Cin_DriverError) Cin_DriverSupportsSampleRate(
  82     const struct Cin_Driver *drv,
  83     unsigned rate);
  84
  85 /** @} */ /* End Driver group. */
  86
  87 #ifdef __cplusplus
  88 } // extern "C"
  89 #endif
  90
  91 #endif /* CIN_DRIVER_H */