A number of people have expressed interest in writing sound card drivers for BeOS. This article describes the interface used by the current audio server to communicate with sound card drivers. Note that this interface is for the current audio server, and that the current audio server will be replaced with something better in a future release. But if you want to write a sound card driver and test it with the current audio server, this is what you will have to support.

These are the ioctl codes used by the audio server:

#include <Drivers.h>

enum {
  SOUND_GET_PARAMS = B_DEVICE_OP_CODES_END,
  SOUND_SET_PARAMS,
  SOUND_SET_PLAYBACK_COMPLETION_SEM,
  SOUND_SET_CAPTURE_COMPLETION_SEM,
  SOUND_RESERVED_1,   /* unused */
  SOUND_RESERVED_2,   /* unused */
  SOUND_DEBUG_ON,     /* unused */
  SOUND_DEBUG_OFF,    /* unused */
  SOUND_WRITE_BUFFER,
  SOUND_READ_BUFFER,
  SOUND_LOCK_FOR_DMA
};

The SOUND_SET_PLAYBACK_COMPLETION_SEM ioctl takes a (sem_id*) argument which points to a semaphore that must be released once for each buffer written. The semaphore should be released when the data in the buffer is no longer needed.

The SOUND_SET_CAPTURE_COMPLETION_SEM ioctl takes a (sem_id*) argument which points to a semaphore that must be released once for each buffer read. The semaphore should be released when the data in the buffer is valid.

The SOUND_WRITE_BUFFER ioctl takes an (audio_buffer_header*) argument which is defined in MediaDefs.h:

typedef struct audio_buffer_header {
  int32 buffer_number;
  int32 subscriber_count;
  bigtime_t time;
  int32 reserved_1;
  int32 reserved_2;
  int32 reserved_3;
  int32 reserved_4;
} audio_buffer_header;

The audio data immediately follows the audio_buffer_header in memory and is in stereo signed 16-bit linear native-endian format. The size in bytes of the audio data plus the audio_buffer_header is stored in the reserved_1 slot of the audio_buffer_header (the audio server was written before the size argument to the ioctl call was implemented). The size and address of the audio data can be derived this way:

audio_buffer_header* header = (audio_buffer_header*) ioctl_arg;
int32 bytes_of_data = header->reserved_1 - sizeof(*header);
int16* addr_of_data = (int16*) (header + 1);

The driver can ignore the buffer_number and subscriber_count slots of the buffer header and should store an estimate of the system_time() corresponding to the beginning of the buffer in the time slot of the buffer header.

The SOUND_WRITE_BUFFER call is allowed to return before the data in the buffer has been consumed but the playback completion semaphore must be released when the buffer can be recycled.

The SOUND_READ_BUFFER ioctl takes an (audio_buffer_header*) argument. The size and address of the data can be computed as above. The time slot should be written with the estimate of the system_time() corresponding to the beginning of the buffer. The call is allowed to return before the buffer is full but the capture completion semaphore must be released as soon as the buffer is full.

The SOUND_GET_PARAMS and SOUND_SET_PARAMS ioctls read and write a set of parameters which correspond to the settings in the sound preferences panel. The ioctl argument is a (sound_setup*) in the following format:

enum adc_source {
  line = 0, cd, mic, loopback
};

enum sample_rate {
  kHz_8_0 = 0, kHz_5_51, kHz_16_0, kHz_11_025, kHz_27_42,
  kHz_18_9, kHz_32_0, kHz_22_05, kHz_37_8 = 9,
  kHz_44_1 = 11, kHz_48_0, kHz_33_075, kHz_9_6, kHz_6_62
};

enum sample_format {};  /* obsolete */

struct channel {
  enum adc_source adc_source;
       /* adc input source */
  char adc_gain;
       /* 0..15 adc gain, in 1.5 dB steps */
  char mic_gain_enable;
       /* non-zero enables 20 dB MIC input gain */
  char cd_mix_gain;
       /* 0..31 cd mix to output gain in -1.5dB steps */
  char cd_mix_mute;
       /* non-zero mutes cd mix */
  char aux2_mix_gain;
       /* unused */
  char aux2_mix_mute;
       /* unused */
  char line_mix_gain;
       /* 0..31 line mix to output gain in -1.5dB steps */
  char line_mix_mute;
       /* non-zero mutes line mix */
  char dac_attn;
       /* 0..61 dac attenuation, in -1.5 dB steps */
  char dac_mute;
       /* non-zero mutes dac output */
};

typedef struct sound_setup {
  struct channel left;
       /* left channel setup */
  struct channel right;
       /* right channel setup */
  enum sample_rate sample_rate;
       /* sample rate */
  enum sample_format playback_format;
       /* ignore (always 16bit-linear) */
  enum sample_format capture_format;
       /* ignore (always 16bit-linear) */
  char dither_enable;
       /* non-zero enables dither on 16 => 8 bit */
  char mic_attn;
       /* 0..64 mic input level */
  char mic_enable;
       /* non-zero enables mic input */
  char output_boost;
       /* ignore (always on) */
  char highpass_enable;
       /* ignore (always on) */
  char mono_gain;
       /* 0..64 mono speaker gain */
  char mono_mute;
       /* non-zero mutes speaker */
} sound_setup;

On PPC systems the mic_attn and mic_enable parameters are used to control the amount of adc to dac "loopback" instead of the microphone input level.

The SOUND_LOCK_FOR_DMA ioctl takes an (audio_buffer_header*) argument but can be ignored except on Macintosh. A Macintosh driver should call lock_memory() on the audio buffer with the B_DMA_IO flag.

The audio server opens the driver named /dev/old/sound. So when you have implemented these ioctl calls and you want to test your driver with the audio server, you can either name it /dev/old/sound or name it something like /dev/old/mydriver and create a symbolic link in your UserBootscript file:

ln -s /dev/old/mydriver /dev/old/sound

The "old" in this path name is to remind you that this is an interface which will be deprecated in the future.

In the previous article on DynaDraw, we built a no-frills app—a basic window and a view, and our drawing algorithm. In this article, we get to the fun part—adding lots of controls which modify how the calligraphy strokes are drawn.

Download the code from:

ftp://ftp.be.com/pub/samples/interface_kit/obsolete/dynadraw2.zip,

compile it, and see how the new features work before getting into the details of this article. I especially dig wireframe mode, which calls StrokePolygon instead of FillPolygon.

Let's start out the way we did last time, looking at what we'd like to do, and what we'll need to do it:

First, we'd like a menu bar across the top of the window. Under it, we'll put two menus: File and Controls. Under File, we'll have the items About, which brings up an About Box, and Quit, which, well, quits. Under Controls, we'll have three items: Tweakables, which brings up a panel for controlling the mass, drag, and other parameters; Color, which allows us to change the color of the pen; and Clear Screen, which clears our drawing.

The Tweakables panel and the Color panel will each have their own windows. R3 introduces a new window type, B_FLOATING_WINDOW, which is perfect for control windows. Floating windows have smaller borders and tabs than regular windows, and they are active whenever the application is active.

The next question is: which object should be responsible for managing these control windows? It's possible to add these duties to the DDWindow class, but if our application grows to include more windows, this approach will be cumbersome. A better solution is to subclass BApplication in an object which manages the creation and destruction of the control windows.

Here's our object list now:

• FilterView, from the first article,

• DDWindow, from the first article,

• TweakWin, which controls pen parameters,

• ColorWin, which controls pen color, and

• DDApp, which manages the application and windows.

   case COLOR_CHG:
    /* get the current color settings,  */
    /* attach to the message            */
    /* and pass it along to the handler */
    rgb_color clr = cc->ValueAsColor();
    swatch->SetViewColor(clr);
    swatch->Invalidate();
    msg->AddInt16("red", clr.red);
    msg->AddInt16("green", clr.green);
    msg->AddInt16("blue", clr.blue);
    handler->PostMessage(msg);
    break;

  fill = new BCheckBox(BRect(25,320,135,340), "fill",
                      "Wireframe", new BMessage(FILL_CHG));
  fill->SetTarget(handler);
    /* send FILL_CHG directly to handler */

  BMenu* menu = new BMenu("File");
  menu->AddItem(new BMenuItem("About",
                new BMessage(B_ABOUT_REQUESTED)));
  menu->AddItem(new BMenuItem("Quit",
                new BMessage(B_QUIT_REQUESTED)));

  /* Both the About and Quit messages should be directed
     to be_app */

  menu->SetTargetForItems(be_app);
  mb->AddItem(menu);

  menu = new BMenu("Controls");
  BMenuItem* tmpItem = new BMenuItem("Tweakables",
    new BMessage(TWEAK_REQ));
  tmpItem->SetTarget(be_app);
  menu->AddItem(tmpItem);

  tmpItem = new BMenuItem("Color", new BMessage(COLOR_REQ));
  tmpItem->SetTarget(be_app);
  menu->AddItem(tmpItem);

  menu->AddSeparatorItem();
  menu->AddItem(new BMenuItem("Clear Screen",
    new BMessage(CLEAR_SCREEN)));

  /* Target not specified for Clear, so the target will
     be DDWindow */

  mb->AddItem(menu);
  AddChild(mb);

   case COLOR_CHG:
     int16 red, green, blue;
     msg->FindInt16("red", &red);
     msg->FindInt16("green", &green);
     msg->FindInt16("blue", &blue);
     SetHighColor(red,green,blue);
     break;

We've "heard" this on e-mail and from newsgroups. We're likely to hear it again at PC Expo, so I thought I'd take a few minutes to clarify our position. The contradiction astute observers point out is this: On the one hand we present ourselves as a media OS, a specialized platform for audio and video applications. We sometimes use the "A/V Linux" sound byte -- and then proceed to show off "non-A/V" applications on our site and, soon, at our booth. Come on, they say, you're really trying to be a general purpose OS—you're competing with Microsoft, you just don't want to admit it!

Let's address the "non-A/V" applications first. We believe the "tractor apps" will come from the field of audio and video activities—editing, synthesizing, producing, and mangling digital media. However, this belief doesn't imply that the BeOS can't or shouldn't be put to other uses.

Imagine for a moment that you're a software developer and all you care about is word processing. Your mother said you shouldn't, but you do, either to aggravate her or just because it's in your soul. Let's further assume you want to make money at it, presumably to show dear old mom who's right. Are you going to try writing a Windows word processor? Of course not. Microsoft Office is the monarch and you'll never impress your mother.

On the BeOS though, the adventure might look risky, but not suicidal. And you can allay family scepticism by telling them about the advantages of Electronic Software Distribution (ESD) and how BeDepot.com is for software authors without knee pads.

"Non-A/V" applications for BeOS have another advantage: users will be happier with their BeOS system, even if their primary use is the "official" media driven one. They still want word processing and e-mail.

Further, imagine a page layout program on the BeOS. It's likely to be livelier, faster, more reactive, and more available to the user than its venerable elders are on the Mac or Windows now. The better feel of the program, its real-time WYSIWYG behavior comes from the programmer, of course. But it also makes a good case for what the BeOS platform has to offer: a good combination of multithreading and—on the right hardware -- multiprocessing, fast graphics, and good APIs.

But, keen observers will insist, this makes you a general-purpose OS, non? Therefore, you're competing with Microsoft and, therefore, you're dead—you just don't realize it yet.

Ah, but this is sophistry. Yes, computers are programmable, in fact they can all be simulated by a simple Turing machine. As a result, all hardware and all system software can do anything. All true enough, if we don't consider how much time, aggravation, or money is involved. So, in the general-purpose office productivity field, I don't believe anyone can beat Microsoft for the time being. Windows, with or without Internet Explorer, Office, Money... your everyday needs are well covered and OEM relationships are such that no new entrants can survive.

But, if Windows can "do" audio and video, it doesn't do it very well. And Windows 98 shows little sign of anything but marginal improvements on what Windows 95 offered. That's where we complement Windows, and the fact that Be developers offer a broader range of applications doesn't make us a competitor to Microsoft Office. In other words, just as Windows can "do" audio and video but doesn't shine there, we can "do" more than A/V, but that's not where we will win.

So, our priority continues to be the A/V domain, where we are most useful. And, when we like a page layout program or an e-mail client on the BeOS, that sentiment doesn't change the nature of our platform.

BeDevTalk is an unmonitored discussion group in which technical information is shared by Be developers and interested parties. In this column, we summarize some of the active threads, listed by their subject lines as they appear, verbatim, in the mail.

To subscribe to BeDevTalk, visit the mailing list page on our web site: http://www.be.com/aboutbe/mailinglists.html.

class C : public A, public B {...}

class B : virtual public A { ... }
class C : virtual public A { ... }

control->TextView()->MakeEditable(false);
window->AddChild(control);
/* The text view is still edible. */

class MyClass : public BView
{
public:

private:
    typedef BView inherited;
};