Be Newsletter

Volume III, Issue 5; February 3, 1999

Table of Contents

• BE ONLINE: Sample Code Reorganized
• BE USERS: Recommend a Reseller
• BE ENGINEERING INSIGHTS: BScreen Improvements for R4, By Trey Boudreau
• Get Ready for Resellers and OEMs, By Dave Johnson
• DEVELOPERS' WORKSHOP: Cults and Kool-Aid, By Doug Fulton
• Another Bedtime Story, By Jean-Louis Gassée

BE ONLINE: Sample Code Reorganized

This week we unveiled the new sample code section of the Be ftp site. Until now, sample code has been organized by the release of the BeOS it was created for. This has made it somewhat difficult to find a piece of sample code, or to know if it has been updated for the most current release.

To solve this problem, the sample code section will now be organized by topic. All the sample code in the top level of a topic will be up-to- date for the current release of the BeOS. Anything that no longer functions will be relegated to an obsolete folder.

It is pretty straight forward. All you need to remember is to look for the appropriate topic or Kit for the sample code, and look inside that folder in the samples directory.

Take a look at the new organization at: [ftp://ftp.be.com/pub/samples/]

BE USERS: Recommend a Reseller

Be Enthusiasts,

Be is actively recruiting resellers for the Be Operating System (BeOS). We're signing up computer stores, software stores, PC assemblers and other potential outlets such as companies aiming at the specialty audio/video market, whether they consist of a single store, local/national distributors, or nationwide chains.

We'd like to enlist your help in this effort. If there is a reseller in your area that you think would be a good place to sell the BeOS, please visit them and let them know about the BeOS and third-party applications.

Let them know that we'll send them a BeOS demo video and an evaluation copy of the BeOS. All they have to do is visit Be on the web at [http: //www.be.com/] and click "Reseller Program" on the home page Deskbar. Resellers can also write to us at [reseller@be.com]. (Note that we'll want to see their reseller/business tax certificate before we send the reseller kit.)

Thanks in advance for your assistance,

Dave Johnson
Sales Manager, Retail Channels
Be, Inc.

If you look at Screen.h and compare the contents to the documentation in the Release 4 Be Book, you'll find a whole slew of new functionality that isn't documented. The fine folks in the technical documentation department didn't ignore these changes. Rather, the responsible engineer (that would be me) didn't get around to telling them about the changes. Oops...

As penance, I'll do a quick rundown of some of the new features in the R4 BScreen. Let's start at the top.

Locking Semantics

The restriction on holding a BScreen for long periods of time has been removed. Creating a BScreen no longer locks the display. This isn't a problem for older programs that use and quickly dispose of the BScreen, but new programs that hold a BScreen for long periods of time must realize that the information returned from various member functions like Frame(), ColorSpace(), etc., will get "stale" if the user changes workspaces, or in the future if the affected window changes displays (graphics devices). New apps need to watch for WorkspaceChanged() notifications and retrieve any relevant info from the BScreen by re-calling the appropriate member functions. No matter how old the BScreen is, the member functions always return current information.

status_t WaitForRetrace();
status_t WaitForRetrace(bigtime_t timeout);

Now that we can hold onto a BScreen for long periods of time, and since the graphics driver architecture in R4 supports notification of vertical retrace events, WaitForRetrace() has been activated. Without parameters, WaitForRetrace() will wait forever for a vertical retrace event. WaitForRetrace(bigtime_t) will wait for up to "timeout" microseconds for the retrace event. Both functions return B_ERROR if the underlying driver doesn't support retrace notification (like R3 drivers running in compatibility mode), or B_OK if the retrace event was caught. WaitForRetrace(timeout) will return B_TIMED_OUT if the timeout expired before the retrace event occurred.

With this info in hand, we can empirically determine the refresh rate of the current display mode with code like the following from my FrameRate test program (available for download at [ftp://ftp.be.com/pub/samples/graphics/FrameRate.zip]:

// One second worth of microseconds
#define ONE_SECOND 1000000
// SLOTS needs to be a power of 2.  256 is just over 2
// seconds worth of measurements at 120Hz and just over 4
// seconds worth of measurements at 60Hz (a common range of
// vertical refresh rates for displays, coincidentally :-)
#define SLOTS 256

int32 rate_calc_thread(void * _rw) {
  RateWindow *rw = (RateWindow *)_rw;
  BScreen bs(rw);
  RateView *rv = rw->rv;
  bigtime_t last_time, tmp_diff;
  bigtime_t this_time, time_diff = 0;
  bigtime_t diffs[SLOTS];
  status_t result;
  int i;

  // if the driver doesn't support retrace events
  // give up now
  result = bs.WaitForRetrace();
  if (result != B_OK) return result;
  last_time = system_time();
  bs.WaitForRetrace();
  this_time = system_time();
  tmp_diff = this_time - last_time;
  // Initialize diffs array so it takes less time to
  // converge.
  for (i = 0; i < SLOTS; i++) {
    diffs[i] = tmp_diff;
    time_diff += tmp_diff;
  }
  i = 1;
  // sync up again before entering the timing loop
  bs.WaitForRetrace();
  last_time = system_time();
  while (rw->run_thread) {
    result = bs.WaitForRetrace();
    this_time = system_time();
    if (result == B_OK) {
      // subtract out the oldest measurement and
      // replace it with the one we just took
      time_diff -= diffs[i];
      diffs[i] = this_time - last_time;
      time_diff += diffs[i];
      // wrap around at the end
      i++; i &= (SLOTS-1);
      last_time = this_time;
      // to reduce jitter, only update the display
      // every 8th frame
      if ((i & 0x7)== 0) {
        rv->rate = ((double)ONE_SECOND * SLOTS)
                    / (double)time_diff;
        // and only if it's not already busy
        if (rw->LockWithTimeout(0) == B_OK) {
          rv->Invalidate();
          rw->Unlock();
        }
      }
    } else return B_ERROR;
  }
  return B_OK;
}

The rest of the program is a fairly boring exercise in a minimalist user interface :-)

It's important to know that it's not guaranteed you can catch every retrace event. If you don't get enough CPU cycles to complete your work and get back to the WaitForRetrace(), you'll drop a frame. Also, your thread might not be the only one running that wants notification of retrace events, so there's no way to guarantee that your code will run during the blanking interval.

New Mode Handling Functions

status_t GetModeList(display_mode **mode_list, uint32 *count);

This code retrieves a list of display_mode structures (defined in Accelerant.h) from the graphics driver for this screen, and updates count to reflect the number of modes. The memory pointed at by **mode_list becomes the responsibility of the caller, and must be free()'d when it's no longer needed.

Note that the list returned by the driver may not be exhaustive -- it may be capable of setting a mode that is not returned in the list, or it may not. It does guarantee that the device in question can support the returned modes, but it doesn't guarantee that your monitor can support them.

status_t GetMode(display_mode *mode);

Retrieve the current screen settings as a display_mode.

status_t
  SetMode(display_mode *mode, bool makeDefault = false);

Configure the screen according to display_mode. If makeDefault is true, this mode will become the default mode for the current workspace.

status_t GetDeviceInfo(accelerant_device_info *adi);
status_t GetPixelClockLimits(display_mode *mode,
  uint32 *low, uint32* high);
status_t
GetTimingConstraints(display_timing_constraints *dtc);

Please ignore these for now, as support for them in the drivers is incomplete. We'll document them as well as add some other functionality here when things settle down (peek in Accelerant.h for clues). I realize the mode setting functions aren't as useful as they could be without these functions, but we're getting there. Thanks for your patience.

Display Power Management

uint32 DPMSCapabilites(void);

Returns a bitmask of DPMS capabilities. For most devices that support DPMS, the returned value will be B_DPMS_ON | B_DPMS_STANDBY | B_DPMS_SUSPEND | B_DPMS_OFF. If DPMS is not supported by the driver, zero is returned.

status_t SetDPMS(uint32 dpms_state);

Set the DPMS state for the device to the requested value. Only one of the DPMS capabilities reported by the driver should specified. Specifying more than one state results in driver-specific behavior -- it may choose from among the specified modes, or ignore the request completely. Returns B_OK if all went well.

uint32 DPMSState(void);

Retrieve the current DPMS status from the device. If the driver doesn't support DPMS, the returned value is undefined.

That pretty much covers it for this article. As more of the graphics devices get R4 drivers, support for these new APIs will increase. R4.1 adds R4-style drivers for the currently supported ATI devices on Intel, as well as for the Matrox Gx00 series of cards. If I'm not mistaken, we'll slip an Intel i740 driver in there, too.

We want all our developers to know that we've launched a drive to recruit resellers for the BeOS. We hope that you'll help out by visiting resellers in your area to tell them about the BeOS. Let them know that they will make money selling it, along with your third-party apps. Please point resellers to our new Reseller Program web pages [http://www.be.com/resellers/programintro.html] to help them get started.

Please take the time to check out this section of the Be web site yourselves. The Reseller Program is a self-contained information source for computer stores, PC assemblers, OEMs, and others who want to start making money selling the BeOS.

A very important page of reseller info that we'll put up ASAP is for YOU. We want to refer resellers, PC assemblers, and OEMs from around the world to YOU, the BeOS developer community. They'll be able to contact you directly to set up deals with the information on this upcoming page.

Now here are two things you can do to prepare for doing business with resellers and others:

1) Develop policies and prices for selling software to resellers and PC builders. Think about special offers you can make to small and large PC assemblers. How about a free "lite" version of your product? If they're putting your product directly on the hard drive of a new PC, can you give them a special "bundle" price, since you aren't paying for disks and manuals?

2) Set up a web page explaining your policies. You don't have to put your confidential reseller prices on the web -- you can ask them to contact you for prices. You should post contact info, phone numbers, and so on. Look at our Reseller Program web page for ideas. Check the web to see how other companies do this.

3) Send me the URL of your reseller-oriented web site, so we can add it to our upcoming ISV reseller programs web page. My e-mail is davej@be.com. I'll take a look at your page, maybe make some recommendations, and then put your contact information on our page.

Yes, that's three things. I just wanted to be sure you're paying attention. This is opportunity knocking.

"Developers' Workshop" is a weekly feature that provides answers to our developers' questions, or topic requests. To submit a question, visit

[http://www.be.com/developers/suggestion_box.html].

We're bellying up to Release 4.1, which means that I can grab some release notes, shove them into an article, and still keep my place in line to the hot tub. Look at some of this:

The BeIDE

The BeIDE editor can look up terms in the Be Book. Alt-Double-Click on a term and you're halfway there. An exact match immediately brings up the appropriate page in your favorite non-integrated HTML viewer; inexact matches go out on the web to spend e-dollars on e-books and e- pornography (buy one, get one free).

External editors, such as, say, Eddie, are supported.

The Find panel has a regular expression formula palette. It's sort of like putting a GUI on grep.

Bits and pieces: You can add a new file to a project from the Save File panel. Selecting and copying files from the Project window adds their names to the clipboard. Build-abort is more robust, if that makes sense.

Other Apps and Preferences

NetPositive supports PNG.

Duncan Wilcox's Blanket is now part of the BeOS, only now it's called ScreenSaver.

There's a new Zip-O-Matic Tracker add-on.

The Find panel presents a handy little draggable icon that represents your new query.

Networking

PPP auto-dialing is supported (again), and has been improved.

Kernel and Kernel Drivers

Down in the kernel, young Cyril has been obsessing over interrupts, alarms, timeouts, the failures of communism, and the curvature of the Swedes. There are at least three new ways to put a stop to all that, no matter what it is: Through the kernel alarm API (set_alarm()), through the driver timer API (add_timer()), or through the new send_signal_etc() call.

There's a new PCMCIA API so you can interface with your Rowenta Iron (oops, that's an iMac, now in all your favorite fruit flavors. What is it about cults and Kool-Aid?)

Miscellaneous improvements: Reduced memory footprint. Improved boot loader (with startling new electric blue graphics). Improved PowerPC compiler and linker. Improved, more reliable kernel debugger (on Intel). More accurate timing for snooze(), timeouts, and the like.

Printing

The new transport layer architecture dramatically increases the number of printing configurations that are supported on the BeOS. There are six transport avenues: Parallel port, Serial port, AppleTalk, Microsoft Network, USB, and Print to File.

And More

Of course there's more, but I'm getting wet

In the past, when Microsoft has pointed to us as a "competitive threat," I called the statement a "DOJ bedtime story." As befits a hot political issue such as the impact of mighty Microsoft on consumers and on the industry, the bedtime story is told in two courts -- in Judge Jackson's court in Washington, DC, and the court of public opinion beyond the limits of judicial review.

In both courts, Microsoft diligently depicts itself as a company under constant threat from dangerous competitors, such as Linux and the BeOS. For two recent examples of the "beleaguered Microsoft" bedtime story, see Chairman Gates' statements at the company's annual shareholders meeting before Christmas, or the statement made by Paul Maritz in District Court Monday last week.

We would feel validated, as we say in California, if we didn't have to wonder why a minuscule company like ours is held in such high regard by the giant. But there's more -- a new bedtime story, from Monday this week. This one is about an integrated browser, which BeOS has, just like Windows 98. See, the story goes -- Be does it too.

Our thanks for the plug, but alas, our NetPositive browser isn't integrated. In fact, we're doing our best to let other browsers -- BeOS versions of Opera and Mozilla, to name two -- flourish on the BeOS platform without playing games with OS features, or with commercial relationships. Our browser is an application, just like a word processor, and it is removed just as easily. I recall us jokingly referring to it in one of our press releases as "DOJ-approved."

When you remove the NetPositive browser, all you lose is the ability to read HTML documents locally or on the Web. One might object that other applications, such as a mail client, are affected. If you remove NetPositive, clicking on a URL no longer takes you "there." Right. If you remove the printer, the word processor no longer prints. This doesn't mean the printer or the driver is "integrated" in the OS in the sense that removing Explorer would cripple Windows 98.

In Microsoft Word, you can paste a "live" Excel document into your text. But that doesn't mean Excel is integral to Word. If you remove Excel it doesn't cripple Word -- it just stops you from doing a "live" paste of a spreadsheet inside your text document.

Microsoft's ignorance of the difference between their way of integrating Explorer and our simpler way of offering NetPositive as a true application puzzles me. The information is there -- it's plain and accessible. Microsoft has purchased many copies of our product and, on Monday last week, they claimed in court they had taken the time to browse our Web site in order to analyze our business. If that claim is true, they should revise the browser bedtime story.