VirtualBox

Changeset 82252 in vbox for trunk/include


Ignore:
Timestamp:
Nov 27, 2019 9:31:53 PM (5 years ago)
Author:
vboxsync
Message:

vmm/pdmaudioifs.h: Style, docs and other nits. First, it's always _FLAGS_ never _FLAG_. Second, enums generally should start with _INVALID = 0 to ensure we don't mistake zero-initialized memory for valid data. Struct member names shall be indented on a tab (+4) boundrary. PDM is part of the VMM, so it follows the VMM coding guidelines strictly. Skip the 'Structure for keeping a ... around' fluff, the first sentence of a structure (or anything else for that matter) documentation shall be brief and to the point. It is automatically turned into a @brief. Furthermore, additional text should be a separate paragraph as it provides details the reader doesn't necessarily need to read. bugref:9218

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/include/VBox/vmm/pdmaudioifs.h

    r76861 r82252  
    194194
    195195#ifndef VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH
    196 # ifdef RT_OS_WINDOWS
     196# if defined(RT_OS_WINDOWS) || defined(RT_OS_OS2)
    197197#  define VBOX_AUDIO_DEBUG_DUMP_PCM_DATA_PATH "c:\\temp\\"
    198198# else
    … …  
    216216{
    217217    /** Invalid format, do not use. */
    218     PDMAUDIOFMT_INVALID,
     218    PDMAUDIOFMT_INVALID = 0,
    219219    /** 8-bit, unsigned. */
    220220    PDMAUDIOFMT_U8,
    … …  
    238238typedef enum PDMAUDIODIR
    239239{
     240    /** Invalid zero value as per usual (guards against using unintialized values). */
     241    PDMAUDIODIR_INVALID = 0,
    240242    /** Unknown direction. */
    241     PDMAUDIODIR_UNKNOWN = 0,
     243    PDMAUDIODIR_UNKNOWN,
    242244    /** Input. */
    243     PDMAUDIODIR_IN      = 1,
     245    PDMAUDIODIR_IN,
    244246    /** Output. */
    245     PDMAUDIODIR_OUT     = 2,
     247    PDMAUDIODIR_OUT,
    246248    /** Duplex handling. */
    247     PDMAUDIODIR_ANY     = 3,
     249    PDMAUDIODIR_ANY,
    248250    /** Hack to blow the type up to 32-bit. */
    249251    PDMAUDIODIR_32BIT_HACK = 0x7fffffff
    … …  
    256258typedef uint32_t PDMAUDIODEVLATSPECSEC;
    257259
    258 /** Audio device flags. Use with PDMAUDIODEV_FLAG_ flags. */
    259 typedef uint32_t PDMAUDIODEVFLAG;
    260 
     260/** @name PDMAUDIODEV_FLAGS_XXX
     261 * @{  */
    261262/** No flags set. */
    262 #define PDMAUDIODEV_FLAGS_NONE            0
     263#define PDMAUDIODEV_FLAGS_NONE            UINT32_C(0)
    263264/** The device marks the default device within the host OS. */
    264 #define PDMAUDIODEV_FLAGS_DEFAULT         RT_BIT(0)
     265#define PDMAUDIODEV_FLAGS_DEFAULT         RT_BIT_32(0)
    265266/** The device can be removed at any time and we have to deal with it. */
    266 #define PDMAUDIODEV_FLAGS_HOTPLUG         RT_BIT(1)
     267#define PDMAUDIODEV_FLAGS_HOTPLUG         RT_BIT_32(1)
    267268/** The device is known to be buggy and needs special treatment. */
    268 #define PDMAUDIODEV_FLAGS_BUGGY           RT_BIT(2)
     269#define PDMAUDIODEV_FLAGS_BUGGY           RT_BIT_32(2)
    269270/** Ignore the device, no matter what. */
    270 #define PDMAUDIODEV_FLAGS_IGNORE          RT_BIT(3)
     271#define PDMAUDIODEV_FLAGS_IGNORE          RT_BIT_32(3)
    271272/** The device is present but marked as locked by some other application. */
    272 #define PDMAUDIODEV_FLAGS_LOCKED          RT_BIT(4)
     273#define PDMAUDIODEV_FLAGS_LOCKED          RT_BIT_32(4)
    273274/** The device is present but not in an alive state (dead). */
    274 #define PDMAUDIODEV_FLAGS_DEAD            RT_BIT(5)
     275#define PDMAUDIODEV_FLAGS_DEAD            RT_BIT_32(5)
     276/** @} */
    275277
    276278/**
    … …  
    279281typedef enum PDMAUDIODEVICETYPE
    280282{
     283    /** Invalid zero value as per usual (guards against using unintialized values). */
     284    PDMAUDIODEVICETYPE_INVALID = 0,
    281285    /** Unknown device type. This is the default. */
    282     PDMAUDIODEVICETYPE_UNKNOWN    = 0,
     286    PDMAUDIODEVICETYPE_UNKNOWN,
    283287    /** Dummy device; for backends which are not able to report
    284288     *  actual device information (yet). */
    … …  
    293297
    294298/**
    295  * Audio device instance data.
     299 * Audio device info (enumeration result).
     300 * @sa PDMAUDIODEVICEENUM, PDMIHOSTAUDIO::pfnGetDevices
    296301 */
    297302typedef struct PDMAUDIODEVICE
    298303{
    299304    /** List node. */
    300     RTLISTNODE         Node;
    301     /** Friendly name of the device, if any. */
    302     char               szName[64];
     305    RTLISTNODE          Node;
     306    /** Additional data which might be relevant for the current context.
     307     * @todo r=bird: I would do this C++ style, having the host specific bits
     308     *       appended after this structure and downcast. */
     309    void               *pvData;
     310    /** Size of the additional data. */
     311    size_t              cbData;
    303312    /** The device type. */
    304     PDMAUDIODEVICETYPE enmType;
     313    PDMAUDIODEVICETYPE  enmType;
     314    /** Usage of the device. */
     315    PDMAUDIODIR         enmUsage;
     316    /** Device flags, PDMAUDIODEV_FLAGS_XXX. */
     317    uint32_t            fFlags;
    305318    /** Reference count indicating how many audio streams currently are relying on this device. */
    306     uint8_t            cRefCount;
    307     /** Usage of the device. */
    308     PDMAUDIODIR        enmUsage;
    309     /** Device flags. */
    310     PDMAUDIODEVFLAG    fFlags;
     319    uint8_t             cRefCount;
    311320    /** Maximum number of input audio channels the device supports. */
    312     uint8_t            cMaxInputChannels;
     321    uint8_t             cMaxInputChannels;
    313322    /** Maximum number of output audio channels the device supports. */
    314     uint8_t            cMaxOutputChannels;
    315     /** Additional data which might be relevant for the current context. */
    316     void              *pvData;
    317     /** Size of the additional data. */
    318     size_t             cbData;
     323    uint8_t             cMaxOutputChannels;
    319324    /** Device type union, based on enmType. */
    320325    union
    … …  
    323328        struct
    324329        {
    325             /** Vendor ID. */
    326             int16_t    VID;
     330            /** Vendor ID.
     331             * @todo r=bird: Why signed?? VUSB uses uint16_t for idVendor and idProduct!  */
     332            int16_t     VID;
    327333            /** Product ID. */
    328             int16_t    PID;
     334            int16_t     PID;
    329335        } USB;
    330336    } Type;
    331 } PDMAUDIODEVICE, *PPDMAUDIODEVICE;
    332 
    333 /**
    334  * Structure for keeping an audio device enumeration.
     337    /** Friendly name of the device, if any. */
     338    char                szName[64];
     339} PDMAUDIODEVICE;
     340/** Pointer to audio device info (enum result). */
     341typedef PDMAUDIODEVICE *PPDMAUDIODEVICE;
     342
     343/**
     344 * An audio device enumeration result.
     345 * @sa PDMIHOSTAUDIO::pfnGetDevices
    335346 */
    336347typedef struct PDMAUDIODEVICEENUM
    … …  
    340351    /** List of audio devices. */
    341352    RTLISTANCHOR    lstDevices;
    342 } PDMAUDIODEVICEENUM, *PPDMAUDIODEVICEENUM;
    343 
    344 /**
    345  * Audio (static) configuration of an audio host backend.
     353} PDMAUDIODEVICEENUM;
     354/** Pointer to an audio device enumeration result. */
     355typedef PDMAUDIODEVICEENUM *PPDMAUDIODEVICEENUM;
     356
     357/**
     358 * Audio configuration (static) of an audio host backend.
    346359 */
    347360typedef struct PDMAUDIOBACKENDCFG
    348361{
    349362    /** The backend's friendly name. */
    350     char     szName[32];
     363    char            szName[32];
    351364    /** Size (in bytes) of the host backend's audio output stream structure. */
    352     size_t   cbStreamOut;
     365    size_t          cbStreamOut;
    353366    /** Size (in bytes) of the host backend's audio input stream structure. */
    354     size_t   cbStreamIn;
     367    size_t          cbStreamIn;
    355368    /** Number of concurrent output (playback) streams supported on the host.
    356369     *  UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
    357     uint32_t cMaxStreamsOut;
     370    uint32_t        cMaxStreamsOut;
    358371    /** Number of concurrent input (recording) streams supported on the host.
    359372     *  UINT32_MAX for unlimited concurrent streams, 0 if no concurrent input streams are supported. */
    360     uint32_t cMaxStreamsIn;
    361 } PDMAUDIOBACKENDCFG, *PPDMAUDIOBACKENDCFG;
     373    uint32_t        cMaxStreamsIn;
     374} PDMAUDIOBACKENDCFG;
     375/** Pointer to a static host audio audio configuration. */
     376typedef PDMAUDIOBACKENDCFG *PPDMAUDIOBACKENDCFG;
    362377
    363378/**
    … …  
    366381 * Currently only two (2) channels, left and right, are supported.
    367382 *
    368  * Note: When changing this structure, make sure to also handle
     383 * @note When changing this structure, make sure to also handle
    369384 *       VRDP's input / output processing in DrvAudioVRDE, as VRDP
    370385 *       expects audio data in st_sample_t format (historical reasons)
    … …  
    374389{
    375390    /** Left channel. */
    376     int64_t i64LSample;
     391    int64_t         i64LSample;
    377392    /** Right channel. */
    378     int64_t i64RSample;
     393    int64_t         i64RSample;
    379394} PDMAUDIOFRAME;
    380395/** Pointer to a single (stereo) audio frame. */
    … …  
    385400typedef enum PDMAUDIOENDIANNESS
    386401{
    387     /** The usual invalid endian. */
    388     PDMAUDIOENDIANNESS_INVALID,
     402    /** The usual invalid value. */
     403    PDMAUDIOENDIANNESS_INVALID = 0,
    389404    /** Little endian. */
    390405    PDMAUDIOENDIANNESS_LITTLE,
    … …  
    399414} PDMAUDIOENDIANNESS;
    400415
     416/** @def PDMAUDIOHOSTENDIANNESS
     417 * The PDMAUDIOENDIANNESS value for the host. */
     418#if defined(RT_LITTLE_ENDIAN)
     419# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
     420#elif defined(RT_BIG_ENDIAN)
     421# define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
     422#else
     423# error "Port me!"
     424#endif
     425
    401426/**
    402427 * Audio playback destinations.
    403428 */
    404 typedef enum PDMAUDIOPLAYBACKDEST
    405 {
     429typedef enum PDMAUDIOPLAYBACKDST
     430{
     431    /** Invalid zero value as per usual (guards against using unintialized values). */
     432    PDMAUDIOPLAYBACKDST_INVALID = 0,
    406433    /** Unknown destination. */
    407     PDMAUDIOPLAYBACKDEST_UNKNOWN = 0,
     434    PDMAUDIOPLAYBACKDST_UNKNOWN,
    408435    /** Front channel. */
    409     PDMAUDIOPLAYBACKDEST_FRONT,
     436    PDMAUDIOPLAYBACKDST_FRONT,
    410437    /** Center / LFE (Subwoofer) channel. */
    411     PDMAUDIOPLAYBACKDEST_CENTER_LFE,
     438    PDMAUDIOPLAYBACKDST_CENTER_LFE,
    412439    /** Rear channel. */
    413     PDMAUDIOPLAYBACKDEST_REAR,
     440    PDMAUDIOPLAYBACKDST_REAR,
    414441    /** Hack to blow the type up to 32-bit. */
    415     PDMAUDIOPLAYBACKDEST_32BIT_HACK = 0x7fffffff
    416 } PDMAUDIOPLAYBACKDEST;
     442    PDMAUDIOPLAYBACKDST_32BIT_HACK = 0x7fffffff
     443} PDMAUDIOPLAYBACKDST;
    417444
    418445/**
    419446 * Audio recording sources.
    420  */
    421 typedef enum PDMAUDIORECSOURCE
     447 *
     448 * @note Because this is almost exclusively used in PDMAUDIODSTSRCUNION where it
     449 *       overlaps with PDMAUDIOPLAYBACKDST, the values starts at 64 instead of 0.
     450 */
     451typedef enum PDMAUDIORECSRC
    422452{
    423453    /** Unknown recording source. */
    424     PDMAUDIORECSOURCE_UNKNOWN = 0,
     454    PDMAUDIORECSRC_UNKNOWN = 64,
    425455    /** Microphone-In. */
    426     PDMAUDIORECSOURCE_MIC,
     456    PDMAUDIORECSRC_MIC,
    427457    /** CD. */
    428     PDMAUDIORECSOURCE_CD,
     458    PDMAUDIORECSRC_CD,
    429459    /** Video-In. */
    430     PDMAUDIORECSOURCE_VIDEO,
     460    PDMAUDIORECSRC_VIDEO,
    431461    /** AUX. */
    432     PDMAUDIORECSOURCE_AUX,
     462    PDMAUDIORECSRC_AUX,
    433463    /** Line-In. */
    434     PDMAUDIORECSOURCE_LINE,
     464    PDMAUDIORECSRC_LINE,
    435465    /** Phone-In. */
    436     PDMAUDIORECSOURCE_PHONE,
     466    PDMAUDIORECSRC_PHONE,
    437467    /** Hack to blow the type up to 32-bit. */
    438     PDMAUDIORECSOURCE_32BIT_HACK = 0x7fffffff
    439 } PDMAUDIORECSOURCE;
     468    PDMAUDIORECSRC_32BIT_HACK = 0x7fffffff
     469} PDMAUDIORECSRC;
     470
     471/**
     472 * Union for keeping an audio stream destination or source.
     473 */
     474typedef union PDMAUDIODSTSRCUNION
     475{
     476    /** Desired playback destination (for an output stream). */
     477    PDMAUDIOPLAYBACKDST enmDst;
     478    /** Desired recording source (for an input stream). */
     479    PDMAUDIORECSRC      enmSrc;
     480} PDMAUDIODSTSRCUNION;
     481/** Pointer to an audio stream src/dst union. */
     482typedef PDMAUDIODSTSRCUNION *PPDMAUDIODSTSRCUNION;
    440483
    441484/**
    … …  
    444487typedef enum PDMAUDIOSTREAMLAYOUT
    445488{
    446     /** Unknown access type; do not use. */
    447     PDMAUDIOSTREAMLAYOUT_UNKNOWN = 0,
     489    /** Invalid zero value as per usual (guards against using unintialized values). */
     490    PDMAUDIOSTREAMLAYOUT_INVALID = 0,
     491    /** Unknown access type; do not use (hdaR3StreamMapReset uses it). */
     492    PDMAUDIOSTREAMLAYOUT_UNKNOWN,
    448493    /** Non-interleaved access, that is, consecutive
    449494     *  access to the data. */
    … …  
    462507    /** Hack to blow the type up to 32-bit. */
    463508    PDMAUDIOSTREAMLAYOUT_32BIT_HACK = 0x7fffffff
    464 } PDMAUDIOSTREAMLAYOUT, *PPDMAUDIOSTREAMLAYOUT;
    465 
     509} PDMAUDIOSTREAMLAYOUT;
     510
     511/**
     512 * Stream channel data block.
     513 */
     514typedef struct PDMAUDIOSTREAMCHANNELDATA
     515{
     516    /** Circular buffer for the channel data. */
     517    PRTCIRCBUF          pCircBuf;
     518    /** Amount of audio data (in bytes) acquired for reading. */
     519    size_t              cbAcq;
     520    /** Channel data flags, PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX. */
     521    uint32_t            fFlags;
     522} PDMAUDIOSTREAMCHANNELDATA;
     523/** Pointer to audio stream channel data buffer. */
     524typedef PDMAUDIOSTREAMCHANNELDATA  *PPDMAUDIOSTREAMCHANNELDATA;
     525
     526/** @name PDMAUDIOSTREAMCHANNELDATA_FLAGS_XXX
     527 *  @{ */
    466528/** No stream channel data flags defined. */
    467 #define PDMAUDIOSTREAMCHANNELDATA_FLAG_NONE      0
    468 
    469 /**
    470  * Structure for keeping a stream channel data block around.
    471  */
    472 typedef struct PDMAUDIOSTREAMCHANNELDATA
    473 {
    474     /** Circular buffer for the channel data. */
    475     PRTCIRCBUF pCircBuf;
    476     /** Amount of audio data (in bytes) acquired for reading. */
    477     size_t     cbAcq;
    478     /** Channel data flags. */
    479     uint32_t   fFlags;
    480 } PDMAUDIOSTREAMCHANNELDATA, *PPDMAUDIOSTREAMCHANNELDATA;
    481 
    482 /**
    483  * Enumeration for standard speaker channel IDs.
     529#define PDMAUDIOSTREAMCHANNELDATA_FLAGS_NONE      UINT32_C(0)
     530/** @} */
     531
     532/**
     533 * Standard speaker channel IDs.
     534 *
    484535 * This can cover up to 11.0 surround sound.
    485536 *
    486  * Note: Any of those channels can be marked / used as the LFE channel (played through the subwoofer).
     537 * @note Any of those channels can be marked / used as the LFE channel (played
     538 *       through the subwoofer).
    487539 */
    488540typedef enum PDMAUDIOSTREAMCHANNELID
    489541{
     542    /** Invalid zero value as per usual (guards against using unintialized values). */
     543    PDMAUDIOSTREAMCHANNELID_INVALID = 0,
    490544    /** Unknown / not set channel ID. */
    491     PDMAUDIOSTREAMCHANNELID_UNKNOWN = 0,
     545    PDMAUDIOSTREAMCHANNELID_UNKNOWN,
    492546    /** Front left channel. */
    493547    PDMAUDIOSTREAMCHANNELID_FRONT_LEFT,
    … …  
    521575
    522576/**
    523  * Structure for mapping a single (mono) channel or dual (stereo) channels of an audio stream (aka stream profile).
    524  *
    525  * An audio stream consists of one or multiple channels (e.g. 1 for mono, 2 for stereo),
    526  * depending on the configuration.
     577 * Structure for mapping a single (mono) channel or dual (stereo) channels onto
     578 * an audio stream (aka stream profile).
     579 *
     580 * An audio stream consists of one or multiple channels (e.g. 1 for mono, 2 for
     581 * stereo), depending on the configuration.
    527582 */
    528583typedef struct PDMAUDIOSTREAMMAP
    529584{
    530585    /** Array of channel IDs being handled.
    531      *  Note: The first (zero-based) index specifies the leftmost channel. */
    532     PDMAUDIOSTREAMCHANNELID    aID[2];
     586     * @note The first (zero-based) index specifies the leftmost channel. */
     587    PDMAUDIOSTREAMCHANNELID     aID[2];
    533588    /** Step size (in bytes) to the channel's next frame. */
    534     size_t                     cbSize;
     589    uint32_t                    cbStep;
    535590    /** Frame size (in bytes) of this channel. */
    536     size_t                     cbFrame;
    537     /** Offset (in bytes) to first frame in the data block. */
    538     size_t                     cbFirst;
    539     /** Offset (in bytes) to the next frame in the data block. */
    540     size_t                     cbOff;
     591    uint32_t                    cbFrame;
     592    /** Byte offset to the first frame in the data block. */
     593    uint32_t                    offFirst;
     594    /** Byte offset to the next frame in the data block. */
     595    uint32_t                    offNext;
    541596    /** Associated data buffer. */
    542     PDMAUDIOSTREAMCHANNELDATA  Data;
    543 } PDMAUDIOSTREAMMAP, *PPDMAUDIOSTREAMMAP;
    544 
    545 /**
    546  * Union for keeping an audio stream destination or source.
    547  */
    548 typedef union PDMAUDIODESTSOURCE
    549 {
    550     /** Desired playback destination (for an output stream). */
    551     PDMAUDIOPLAYBACKDEST Dest;
    552     /** Desired recording source (for an input stream). */
    553     PDMAUDIORECSOURCE    Source;
    554 } PDMAUDIODESTSOURCE, *PPDMAUDIODESTSOURCE;
     597    PDMAUDIOSTREAMCHANNELDATA   Data;
     598} PDMAUDIOSTREAMMAP;
     599/** Pointer to an audio stream channel mapping. */
     600typedef PDMAUDIOSTREAMMAP *PPDMAUDIOSTREAMMAP;
    555601
    556602/**
    … …  
    560606{
    561607    /** Sample width (in bytes). */
    562     uint8_t     cBytes;
     608    uint8_t     cbSample;
    563609    /** Number of audio channels. */
    564610    uint8_t     cChannels;
    565     /** Shift count used for faster calculation of various
    566      *  values, such as the alignment, bytes to frames and so on.
    567      *  Depends on number of stream channels and the stream format
    568      *  being used.
    569      *
    570      ** @todo Use some RTAsmXXX functions instead?
    571      */
     611    /** Shift count used with PDMAUDIOPCMPROPS_F2B and PDMAUDIOPCMPROPS_B2F.
     612     * Depends on number of stream channels and the stream format being used, calc
     613     * value using PDMAUDIOPCMPROPS_MAKE_SHIFT.
     614     * @sa   PDMAUDIOSTREAMCFG_B2F, PDMAUDIOSTREAMCFG_F2B
     615     * @todo r=bird: The original brief description: "Shift count used
     616     *       for faster calculation of various values, such as the alignment, bytes
     617     *       to frames and so on."  I cannot make heads or tails from that.
     618     * @todo Use some RTAsmXXX functions instead? */
    572619    uint8_t     cShift;
    573620    /** Signed or unsigned sample. */
    … …  
    578625    uint32_t    uHz;
    579626} PDMAUDIOPCMPROPS;
     627AssertCompileSize(PDMAUDIOPCMPROPS, 8);
    580628AssertCompileSizeAlignment(PDMAUDIOPCMPROPS, 8);
    581629/** Pointer to audio stream properties. */
    582630typedef PDMAUDIOPCMPROPS *PPDMAUDIOPCMPROPS;
    583631
     632/** @name Macros for use with PDMAUDIOPCMPROPS
     633 * @{ */
    584634/** Initializor for PDMAUDIOPCMPROPS. */
    585635#define PDMAUDIOPCMPROPS_INITIALIZOR(a_cBytes, a_fSigned, a_cCannels, a_uHz, a_cShift, a_fSwapEndian) \
    … …  
    589639#define PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS(cBytes, cChannels)    ((cChannels == 2) + (cBytes / 2))
    590640/** Calculates the cShift value of a PDMAUDIOPCMPROPS structure. */
    591 #define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps)                     PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cBytes, (pProps)->cChannels)
     641#define PDMAUDIOPCMPROPS_MAKE_SHIFT(pProps)     PDMAUDIOPCMPROPS_MAKE_SHIFT_PARMS((pProps)->cbSample, (pProps)->cChannels)
    592642/** Converts (audio) frames to bytes.
    593643 *  Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
    594 #define PDMAUDIOPCMPROPS_F2B(pProps, frames)                    ((frames) << (pProps)->cShift)
     644#define PDMAUDIOPCMPROPS_F2B(pProps, frames)    ((frames) << (pProps)->cShift)
    595645/** Converts bytes to (audio) frames.
    596646 *  Needs the cShift value set correctly, using PDMAUDIOPCMPROPS_MAKE_SHIFT. */
    597 #define PDMAUDIOPCMPROPS_B2F(pProps, cb)                        (cb >> (pProps)->cShift)
     647#define PDMAUDIOPCMPROPS_B2F(pProps, cb)        ((cb) >> (pProps)->cShift)
     648/** @}   */
    598649
    599650/**
    … …  
    602653typedef struct PDMAUDIOSTREAMCFG
    603654{
    604     /** Friendly name of the stream. */
    605     char                     szName[64];
    606655    /** Direction of the stream. */
    607     PDMAUDIODIR              enmDir;
     656    PDMAUDIODIR             enmDir;
    608657    /** Destination / source indicator, depending on enmDir. */
    609     PDMAUDIODESTSOURCE       DestSource;
     658    PDMAUDIODSTSRCUNION     u;
    610659    /** The stream's PCM properties. */
    611     PDMAUDIOPCMPROPS         Props;
     660    PDMAUDIOPCMPROPS        Props;
    612661    /** The stream's audio data layout.
    613662     *  This indicates how the audio data buffers to/from the backend is being layouted.
    … …  
    622671     *      Can be one or many streams at once, depending on the stream's mixing buffer setup.
    623672     *      The audio data will get handled as PDMAUDIOFRAME frames without any modification done. */
    624     PDMAUDIOSTREAMLAYOUT     enmLayout;
     673    PDMAUDIOSTREAMLAYOUT    enmLayout;
    625674    /** Device emulation-specific data needed for the audio connector. */
    626675    struct
    … …  
    628677        /** Scheduling hint set by the device emulation about when this stream is being served on average (in ms).
    629678         *  Can be 0 if not hint given or some other mechanism (e.g. callbacks) is being used. */
    630         uint32_t             uSchedulingHintMs;
     679        uint32_t            uSchedulingHintMs;
    631680    } Device;
    632681    /**
    … …  
    641690         *  This value reflects the number of audio frames in between each hardware interrupt on the
    642691         *  backend (host) side. 0 if not set / available by the backend. */
    643         uint32_t             cfPeriod;
     692        uint32_t            cfPeriod;
    644693        /** (Ring) buffer size (in audio frames). Often is a multiple of cfPeriod.
    645694         *  0 if not set / available by the backend. */
    646         uint32_t             cfBufferSize;
     695        uint32_t            cfBufferSize;
    647696        /** Pre-buffering size (in audio frames). Frames needed in buffer before the stream becomes active (pre buffering).
    648697         *  The bigger this value is, the more latency for the stream will occur.
    649698         *  0 if not set / available by the backend. UINT32_MAX if not defined (yet). */
    650         uint32_t             cfPreBuf;
     699        uint32_t            cfPreBuf;
    651700    } Backend;
     701    /** Friendly name of the stream. */
     702    char                    szName[64];
    652703} PDMAUDIOSTREAMCFG;
    653704AssertCompileSizeAlignment(PDMAUDIOPCMPROPS, 8);
    … …  
    655706typedef PDMAUDIOSTREAMCFG *PPDMAUDIOSTREAMCFG;
    656707
    657 
    658708/** Converts (audio) frames to bytes. */
    659709#define PDMAUDIOSTREAMCFG_F2B(pCfg, frames) ((frames) << (pCfg->Props).cShift)
    … …  
    661711#define PDMAUDIOSTREAMCFG_B2F(pCfg, cb)  (cb >> (pCfg->Props).cShift)
    662712
    663 #if defined(RT_LITTLE_ENDIAN)
    664 # define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_LITTLE
    665 #elif defined(RT_BIG_ENDIAN)
    666 # define PDMAUDIOHOSTENDIANNESS PDMAUDIOENDIANNESS_BIG
    667 #else
    668 # error "Port me!"
    669 #endif
    670 
    671713/**
    672714 * Audio mixer controls.
    … …  
    674716typedef enum PDMAUDIOMIXERCTL
    675717{
     718    /** Invalid zero value as per usual (guards against using unintialized values). */
     719    PDMAUDIOMIXERCTL_INVALID = 0,
    676720    /** Unknown mixer control. */
    677     PDMAUDIOMIXERCTL_UNKNOWN = 0,
     721    PDMAUDIOMIXERCTL_UNKNOWN,
    678722    /** Master volume. */
    679723    PDMAUDIOMIXERCTL_VOLUME_MASTER,
    … …  
    693737
    694738/**
    695  * Audio stream commands. Used in the audio connector
    696  * as well as in the actual host backends.
     739 * Audio stream commands.
     740 *
     741 * Used in the audio connector as well as in the actual host backends.
    697742 */
    698743typedef enum PDMAUDIOSTREAMCMD
    699744{
     745    /** Invalid zero value as per usual (guards against using unintialized values). */
     746    PDMAUDIOSTREAMCMD_INVALID = 0,
    700747    /** Unknown command, do not use. */
    701     PDMAUDIOSTREAMCMD_UNKNOWN = 0,
     748    PDMAUDIOSTREAMCMD_UNKNOWN,
    702749    /** Enables the stream. */
    703750    PDMAUDIOSTREAMCMD_ENABLE,
    … …  
    738785     *  the most silent and 255 the loudest value. */
    739786    uint8_t uRight;
    740 } PDMAUDIOVOLUME, *PPDMAUDIOVOLUME;
     787} PDMAUDIOVOLUME;
     788/** Pointer to audio volume settings. */
     789typedef PDMAUDIOVOLUME  *PPDMAUDIOVOLUME;
    741790
    742791/** Defines the minimum volume allowed. */
    … …  
    746795
    747796/**
    748  * Structure for holding rate processing information
    749  * of a source + destination audio stream. This is needed
    750  * because both streams can differ regarding their rates
    751  * and therefore need to be treated accordingly.
     797 * Rate processing information of a source & destination audio stream.
     798 *
     799 * This is needed because both streams can differ regarding their rates and
     800 * therefore need to be treated accordingly.
    752801 */
    753802typedef struct PDMAUDIOSTREAMRATE
    … …  
    755804    /** Current (absolute) offset in the output
    756805     *  (destination) stream. */
    757     uint64_t       dstOffset;
     806    uint64_t        dstOffset;
    758807    /** Increment for moving dstOffset for the
    759808     *  destination stream. This is needed because the
    760809     *  source <-> destination rate might be different. */
    761     uint64_t       dstInc;
     810    uint64_t        dstInc;
    762811    /** Current (absolute) offset in the input
    763812     *  stream. */
    764     uint32_t       srcOffset;
     813    uint32_t        srcOffset;
     814    /** Explicit alignment padding. */
     815    uint32_t        u32AlignmentPadding;
    765816    /** Last processed frame of the input stream.
    766817     *  Needed for interpolation. */
    767     PDMAUDIOFRAME  srcFrameLast;
    768 } PDMAUDIOSTREAMRATE, *PPDMAUDIOSTREAMRATE;
    769 
    770 /**
    771  * Structure for holding mixing buffer volume parameters.
    772  * The volume values are in fixed point style and must
    773  * be converted to/from before using with e.g. PDMAUDIOVOLUME.
     818    PDMAUDIOFRAME   srcFrameLast;
     819} PDMAUDIOSTREAMRATE;
     820/** Pointer to rate processing information of a stream. */
     821typedef PDMAUDIOSTREAMRATE *PPDMAUDIOSTREAMRATE;
     822
     823/**
     824 * Mixing buffer volume parameters.
     825 *
     826 * The volume values are in fixed point style and must be converted to/from
     827 * before using with e.g. PDMAUDIOVOLUME.
    774828 */
    775829typedef struct PDMAUDMIXBUFVOL
    776830{
    777831    /** Set to @c true if this stream is muted, @c false if not. */
    778     bool    fMuted;
    779     /** Left volume to apply during conversion. Pass 0
    780      *  to convert the original values. May not apply to
    781      *  all conversion functions. */
    782     uint32_t uLeft;
    783     /** Right volume to apply during conversion. Pass 0
    784      *  to convert the original values. May not apply to
    785      *  all conversion functions. */
    786     uint32_t uRight;
    787 } PDMAUDMIXBUFVOL, *PPDMAUDMIXBUFVOL;
    788 
    789 /**
    790  * Structure for holding frame conversion parameters for
    791  * the audioMixBufConvFromXXX / audioMixBufConvToXXX macros.
     832    bool            fMuted;
     833    /** Left volume to apply during conversion.
     834     * Pass 0 to convert the original values. May not apply to all conversion functions. */
     835    uint32_t        uLeft;
     836    /** Right volume to apply during conversion.
     837     * Pass 0 to convert the original values. May not apply to all conversion functions. */
     838    uint32_t        uRight;
     839} PDMAUDMIXBUFVOL;
     840/** Pointer to mixing buffer volument parameters. */
     841typedef PDMAUDMIXBUFVOL *PPDMAUDMIXBUFVOL;
     842
     843/*
     844 * Frame conversion parameters for the audioMixBufConvFromXXX / audioMixBufConvToXXX functions.
    792845 */
    793846typedef struct PDMAUDMIXBUFCONVOPTS
    … …  
    810863
    811864/**
    812  * Note: All internal handling is done in audio frames,
    813  *       not in bytes!
     865 * Note: All internal handling is done in audio frames, not in bytes!
     866 * @todo r=bird: What does this node actually apply to?
    814867 */
    815868typedef uint32_t PDMAUDIOMIXBUFFMT;
    … …  
    841894typedef FNPDMAUDIOMIXBUFCONVTO *PFNPDMAUDIOMIXBUFCONVTO;
    842895
     896/** Pointer to audio mixing buffer.  */
    843897typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
     898
     899/**
     900 * Audio mixing buffer.
     901 */
    844902typedef struct PDMAUDIOMIXBUF
    845903{
    … …  
    898956} PDMAUDIOMIXBUF;
    899957
     958/** @name PDMAUDIOFILE_FLAG_XXX
     959 * @{ */
    900960typedef uint32_t PDMAUDIOFILEFLAGS;
    901 
    902961/** No flags defined. */
    903962#define PDMAUDIOFILE_FLAG_NONE          0
    … …  
    906965/** Audio file flag validation mask. */
    907966#define PDMAUDIOFILE_FLAG_VALID_MASK    0x1
     967/** @} */
    908968
    909969/** Audio file default open flags. */
    … …  
    12911351     * @param   ppStream             Pointer where to return the created audio stream on success.
    12921352     */
    1293     DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
     1353    DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAMCFG pCfgHost,
     1354                                                PPDMAUDIOSTREAMCFG pCfgGuest, PPDMAUDIOSTREAM *ppStream));
    12941355
    12951356    /**
    … …  
    15181579    /**
    15191580     * Creates an audio stream using the requested stream configuration.
    1520      * If a backend is not able to create this configuration, it will return its best match in the acquired configuration
    1521      * structure on success.
     1581     *
     1582     * If a backend is not able to create this configuration, it will return its
     1583     * best match in the acquired configuration structure on success.
    15221584     *
    15231585     * @returns VBox status code.
    … …  
    15261588     * @param   pCfgReq             Pointer to requested stream configuration.
    15271589     * @param   pCfgAcq             Pointer to acquired stream configuration.
    1528      */
    1529     DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
     1590     * @todo    r=bird: Implementation (at least Alsa) seems to make undocumented
     1591     *          assumptions about the content of @a pCfgAcq.
     1592     */
     1593    DECLR3CALLBACKMEMBER(int, pfnStreamCreate, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
     1594                                                PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq));
    15301595
    15311596    /**
    … …  
    15461611     * @param   enmStreamCmd        The stream command to issue.
    15471612     */
    1548     DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd));
     1613    DECLR3CALLBACKMEMBER(int, pfnStreamControl, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream,
     1614                                                 PDMAUDIOSTREAMCMD enmStreamCmd));
    15491615
    15501616    /**
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette