Changeset 12

Show
Ignore:
Timestamp:
07/30/02 22:07:08 (6 years ago)
Author:
rossbencina
Message:

- added paNullStreamInfo constant
- removed the PaHostApiSpecificStreamInfo? struct from the public PortAudio interface, and instead documented as set of standard header fields which must be used in implementation's host api specific stream info structs
- revoked type change of inputStreamInfo and outputStreamInfo - they will remain void* as in V18

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • pa_proposals/trunk/008-HostAPISpecificOpenStreamParameters.html

    r4 r12  
    1818<P><A href="index.html">Enhancement Proposals Index</A>, 
    1919<A href="http://www.portaudio.com/">PortAudio Home Page</A></P> 
    20 <P>Updated: July 26, 2002 </P> 
     20<P>Updated: July 31, 2002 </P> 
    2121 
    2222 
    … …  
    2424 
    2525<P> 
    26 Although this proposal has been implemented in v19-devel, it still requires further discussion.  
    27 We need to decide whether the host-specific 
    28 data associated with PaHostApiSpecificStreamInfo should immediately follow the PaHostApiSpecificStreamInfo or whether PaHostApiSpecificStreamInfo should contain a pointer to the host specific data. We should also consider whether it is worth defining a special constant paNullStreamInfo to be passed to the streamInfo parameters to Pa_OpenStream() when no stream info is being used. 
    29 </P> 
    30  
     26This proposal is sufficiently well defined to be implemented. It has been partially implemented 
     27in v19-devel, however the current proposal no longer utilises the PaHostApiSpecificStreamInfo 
     28structure currently used in v19-devel. 
     29</P>  
    3130<H4>Dependencies</H4> 
    3231 
    … …  
    4746 
    4847<P> 
    49 The following structure could be defined as a common header for all data structures passed to the inputDriverInfo and outputDriverInfo parameters of Pa_OpenStream: 
    50 </P> 
    51  
     48The inputDriverInfo and outputDriverInfo to Pa_OpenStream() will be renamed inputStreamInfo and outputStreamInfo. 
     49</P> 
     50 
     51<P> 
     52A special constant paNullStreamInfo will be defined, which can be used in the inputStreamInfo 
     53and outputStreamInfo parameters. 
     54</P 
     55 
     56<PRE> 
     57#define paNullStreamInfo ((void*)0) 
     58</P> 
     59 
     60<P> 
     61All data structures defined by implementations to be passed 
     62to the inputStreamInfo and outputStreamInfo parameters of Pa_OpenStream 
     63must begin with the following fields: 
     64</P> 
     65 
     66<PRE> 
     67unsigned long size;    /* size of whole structure including this header */ 
     68PaHostApiTypeId hostApiType; /* host API for which this data is intended */ 
     69unsigned long version; /* structure version */ 
     70</PRE> 
     71 
     72<P> 
     73The common infrastructure will expect these fields to be present, and to contain valid information. 
     74</P> 
     75 
     76 
     77<P> 
     78The following host API specific extensions will be placed in separate header files rather than being placed in portaudio.h 
     79</P> 
     80 
     81<P>___</P> 
     82 
     83<P>The following structure is proposed for passing device names to the OSS implementation:</P> 
    5284<PRE> 
    5385struct{ 
    5486    unsigned long size;    /* size of whole structure including this header */ 
    55     PaHostApiTypeId hostApiType; /* host API for which this data is intended */ 
    56     unsigned long version; /* structure version */ 
    57 }PaHostApiSpecificStreamInfo; 
    58 </PRE> 
    59  
    60 <P> 
    61 The inputDriverInfo and outputDriverInfo to Pa_OpenStream() will be renamed inputStreamInfo and outputStreamInfo and will have their types changed from void* to PaHostApiSpecificStreamInfo*. 
    62 </P> 
    63  
    64  
    65 <P> 
    66 The following host API specific extensions will be placed in separate header files rather than being placed in portaudio.h 
    67 </P> 
    68  
    69 <P>___</P> 
    70  
    71 <P>The following structure is proposed for passing device names to the OSS implementation:</P> 
    72 <PRE> 
    73 struct{ 
    74     PaHostApiSpecificStreamInfo header; 
     87        PaHostApiTypeId hostApiType; /* host API for which this data is intended */ 
     88        unsigned long version; /* structure version */ 
     89 
    7590    char *deviceName; 
    7691}PaOSSSpecificStreamInfo; 
    … …  
    113128 
    114129typedef struct PaWinMmeStreamInfo{ 
    115     PaHostApiSpecificStreamInfo header; 
     130    unsigned long size;    /* size of whole structure including this header */ 
     131        PaHostApiTypeId hostApiType; /* host API for which this data is intended */ 
     132        unsigned long version; /* structure version */ 
    116133 
    117134    unsigned long flags; 
    … …  
    147164 
    148165<P> 
    149 Some objections were raised regarding changing the type of inputDriverInfo and outputDriverInfo from void* to PaHostAPISpecificInfo*, as this may require clients to explicitly cast to PaHostAPISpecificInfo* when passing NULL. However the added semantic and type safety advantages were considered more valuable. 
     166Originally this proposal involved declaring a common header structure which would 
     167be embedded at the head of each host-api specific stream info structure: 
     168</P> 
     169<PRE> 
     170struct{ 
     171    unsigned long size;    /* size of whole structure including this header */ 
     172    PaHostApiTypeId hostApiType; /* host API for which this data is intended */ 
     173    unsigned long version; /* structure version */ 
     174}PaHostApiSpecificStreamInfo; 
     175</PRE> 
     176 
     177<P> 
     178However, the unidiomatic type casts required to make the use of this structure transparent 
     179lead us to the current approach, where the presence of the header structure is  
     180implicit. 
     181</P> 
     182 
     183<P> 
     184When PaHostApiSpecificStreamInfo was still declared, we intended to change the type of the 
     185streamInfor parameters from void* to PaHostApiSpecificStreamInfo*. Some objections were raised  
     186to this, as it may have required clients to explicitly cast to PaHostAPISpecificInfo* when passing NULL. However the added semantic and type safety advantages were considered more valuable. The current 
     187proposal leaves these parameters as NULL. 
    150188</P> 
    151189 
    … …  
    165203</BODY> 
    166204</HTML> 
     205