Hi Bryan,
Included below is a copy of Seeing Gray.
It looks like the KB may not be back up until Monday. At this point its a
database issue and we have a few different people in Palm and 3Com working on
it. We are working as quickly as we can to get the KB up as soon as possible.
I'm really sorry these systems have been down for so long. This has been a very
frustrating experience.
Anyway, here is "Seeing Gray".
Ryan Robertson
Palm Development Support
Seeing Gray
Q: I heard a rumor that the Palm III had grayscale support. How do I use
grayscale in PalmOS 3.0?
A: In general, you don't. Just like in 1.0 and 2.0, there isn't any official
support for drawing in gray in the 3.0 release of the Palm OS.
Q: Okay, so officially I don't use grayscale. But how about if I really want
to?
A: Just like in 1.0 and 2.0, you can hack. If you're going to do that, we have
some advice.
First and foremost, you can and should use the one new supported grayscale
routine, ScrDisplayMode, to query or set the current depth of the display before
you do any hacking. You used to do this by
setting the Dragonball registers yourself, and we'd really prefer it if you
stopped that and used ScrDisplayMode instead. By doing this you avoid three
potential problems: 1) switching to gray but
assuming the device needs to be set to 1-bit mode for system UI, 2) writing to
screen memory assuming that it's 1-bit deep, and 3) assuming the CPU in the
device has a register layout like the
Dragonball.
Here's how to make sure the screen is what you expect at app startup. The code
is PalmOS 3.0 (and later) only, so you'll have to do something else for 1.0 and
2.0 releases.
PilotMain()
{
if (normalLaunch)
{
DWord requiredDepth = 2; // Apps needing B/W should use 1, grayscale
apps use 2
err = ScrDisplayMode(scrDisplayModeSet, NULL, NULL, &requiredDepth,
NULL);
if (err)
{
Alert("This app is not designed to work with this device's screen.")
return err;
}
DoApp();
err = ScrDisplayMode(scrDisplayModeSetToDefaults, NULL, NULL, NULL,
NULL);
}
}
At some point, we may have devices that run in other than 1-bit deep mode by
default. On those machines, if you "reset" the device to 1-bit, you'll either
annoy the user or crash the system. Also, if you
write 1-bit data directly to screen memory, you'll either annoy the user or
crash the system.
You can experiment with running the whole OS in 2-bit mode on Palm III devices
(and in the Mac Simulator with the 3.0 SDK and PalmOS Emulator with 3.0 ROM), by
using the following code to set the
default depth to 2.
From PalmOS 3.0 SystemMgr.h:
#define sysFtrNumDisplayDepth 7 // Display depth
// Result is the "default" display depth for the screen.
// This value is used by ScrDisplayMode when setting the default
display depth.
In your app:
//-----------------------------------------------------------------------
// FUNCTION: SetDefaultDepth
// DESCRIPTION: Set the default depth for the system
// PARAMETERS: New default depth, pass 1 or 2 for that depth.
//-----------------------------------------------------------------------
static Err SetDefaultDepth(DWord newDefaultDepth)
{
Err err = FtrSet(sysFtrCreator, sysFtrNumDisplayDepth, newDefaultDepth);
if (!err)
err = ScrDisplayMode(scrDisplayModeSetToDefaults, NULL, NULL, NULL,
NULL);
return err ;
}
There isn't any supported API to draw to the screen in gray. You can do that by
using the current hacks that write screen memory. Once again, when you do this
we'd prefer you use the new API to verify
that the screen is as expected before you mess with it.
Q: Okay, thanks, that's cool. But I see some stuff in the headers that kind of
looks like API to draw in gray. Can I use it?
A: It's not supported.
Q: Oh, OK. ... But can I use it?
A: Well, you can jump to any address or call any trap and pass in any data you
want, so we can't really stop you, can we? However, one reason you might not
want to write code that uses these APIs is that
the traps and structures may change, maybe even as soon as the next release,
breaking your code. Are you willing to live with the fact that you might have to
throw your code away?
Q: Um, well... maybe. Would it be worth it?
A: Probably not.
Q: Tell me anyway.
A: Well, since you insist.
Grayscale Bitmaps:
If you look in the WindowNew.h header file, you'll see some changes to the
BitmapType struct. In particular, notice that there is a pixelSize and version
field in the structure, and the nextDepthOffset
field.
Also notice the hasColorTable field in the flags structure, and the new
ColorTableType struct. For starters, ignore the ColorTable stuff. The PalmOS 3.0
ignores it. Please leave the 'hasColorTable' flag
set to 0. Also, the comment about colorTable data being present if pixelSize is
2 is wrong. The hasColorTable field in flags is used as a test, and if that
flag is 0, then it's assumed there is no colorTable
data.
Anyway, the OS now attempts to draw bitmaps that are 1- or 2-bits deep. Bitmap
families can be created by using the nextDepthOffset field to indicate that
starting after the bits in the current bitmap there
will be another BitmapType struct with a greater depth. (Bitmaps must be in
order of increasing depth, and you shouldn't try to include 2 bitmaps of the
same depth, unpredictable things will happen.)
The color table for 2-bit deep bitmaps is the obvious one. 0 = white, 1 = light
gray, 2 = dark gray, and 3 = black.
When one of these structs is passed to WinDrawBitmap, the OS will attempt to
use the image that most closely matches the depth of the display. If a matching
image is not found, the largest depth less
than or equal to the current depth will be used. If there isn't one, the
smallest depth will be used. Said another way, the OS tries to use 1-bit images
on 1-bit displays and 2-bit images on 2-bit displays, but
if it can't find them it will draw 1-bit bitmaps to 2-bit displays and 2-bit
bitmaps to 1-bit displays, albeit more slowly. Don't bother experimenting with
bitmaps greater than 2 bits deep.
Q: Are there any tools for creating these bitmaps?
A: None that are released or distributed, sorry.
Q: But what if I really want to?
A: Well, you could always create the tBMP resources yourself, using the
definitions in WindowNew.h.
Q: Yuck, what a pain. You guys must have done something to test the APIs,
right?
A: While neither confirming nor denying that we tested these APIs, I do notice
that the grayscale drawing code works pretty well...
Q: So what did you do?
A: We updated our internal tools.
Q: Don't make me work so hard! Can I get these updated tools?
A: Actually, odds are good you already have them, since they seem to have crept
into the latest MW release. The problem is, they're not supported so you can't
actually use them.
Q: You keep saying that, but what if I really want to use them?
A: You still can't. ...unless... are you willing to do the work necessary to
change your app later when the tools change? That is, do you accept that by
doing this stuff, you're writing a very tool-dependent
application, which probably won't build the same way on future releases.
Q: Yes! I'll do anything for gray.
A: Well, since you're so enthusiastic... welcome to hackerdom.
PilotRez looks for "flags" embedded within the NAME of the Mac PICT resource,
and these flags control what kind of tBMP the PICT is translated into. (I have
no idea what the Windows tools do--sorry.)
The flags must be delimited by "/" characters at the beginning and end, and
must appear first in the name.
Read this next section carefully, the meaning of the flags is non-intuitive.
The flags are:
-1 Include a 1-bit deep image
-2 Include a 2-bit deep image
-c Disable compression
"/-1/" is the default setting, and produces a 1-bit deep compressed tBMP. This
applies if no flags are specified.
Note that if you include the -2 flag, you DO NOT get a 1-bit deep image in the
tBMP unless you ALSO include the -1 flag.
Note that the sense of the -c flag is reversed. Including the flag turns
compression OFF.
For example, a PICT with the name "/-2/foo" produces ONLY a 2-bit deep,
compressed bitmap. A PICT with the name "/-1 -2/bar" produces a tBMP with both a
1-bit and 2-bit deep compressed bitmap. A
PICT with the name "/-c/baz" produces an uncompressed, 1-bit deep bitmap.
For now, you always want your bitmaps to include a 1-bit deep image, so that
they will render properly on earlier releases of the OS. This means you should
always include the -1 flag.
Q: Okay, well, it's worth a try anyway. You said this probably wouldn't work in
the future, can you say more about that?
A: Yes. This approach has some drawbacks. For one thing, it's not possible to
specify different bitmaps for the 1-bit and 2-bit deep images in a single tBMP
resource. That means your 1-bit deep image
will be a down-resolution rendered version of your 2-bit deep image. Also,
there's no way to "mix" compressions among the image depths in a single tBMP.
(Though that's of dubious utility.)
We will almost certainly be updating the tools to eliminate these drawbacks if
and when grayscale drawing becomes a supported part of the Palm OS. We almost
certainly will not continue to use flags in
the name of a resource to control these settings.
Q: Well, that's neat anyway, and I might even be able to use it. But what's
this stuff about foreground and background colors, and what's RGBColorType for?
A: Aren't you persistent! Well, for starters that's even more likely to change
than the gray bitmap stuff. In fact, using these routines is almost certainly a
complete waste of time.
Q: Well, I just have an insatiable curiousity about this stuff, and I think
it'd be really neat to draw in gray, and honestly I've got way too much time on
my hands anyway, so will you tell me more?
A: Wow, you sure are persistent. Okay, you've talked me into it.
When drawing text, lines and rectangles, and 1-bit deep bitmaps, the OS will
occasionally attempt to use the current foreColor and backColor. These colors
are set calling WinSetColors and passing in an
RGB value represented as an RGBColorType. For 2-bit grayscale, only white,
black, and 2 shades of gray are available, so a 24-bit RGB value is definitely
overkill, but that's what you pass. Only these
values are really useful:
static const RGBColorType black = {0x00, 0x00, 0x00, 0x00};
static const RGBColorType dkGray = {0x00, 0x55, 0x55, 0x55};
static const RGBColorType ltGray = {0x00, 0xAA, 0xAA, 0xAA};
static const RGBColorType white = {0x00, 0xFF, 0xFF, 0xFF};
Anyway, when you call WinSetColors, you get back the old foreground and
background colors. Make sure you save these values, and restore them when you're
done drawing. If you leave the colors in a
state other than they were when you started, unpredictable things will happen.
Once you've set the foreground and background color the way you want, you just
draw using the same routines you're used to. Some of them will do what you
expect, and some won't. In particular,
transfer modes other than scrCopy will probably not do what you expect.
Q: Hey, thanks! I can't wait to add some grayed out buttons and menu items to
my app!
A: No no no! That would look ugly and waste space. Please try to stick to the
current style guidelines, and don't make me regret sharing this info with you!
Q: Good point. But I can't wait to port my grayscale game to the new APIs!
A: You should probably think twice about that. You currently have hacks to draw
in gray that work on all the PalmOS devices. Why would you change them so they
only work on one? Future compatibility
isn't a concern, because there's just as much chance that above APIs will break
on the next device as there is that your hacks will break. Writing to screen
memory is relatively efficient, it's actually slower
to mess with RGB values and system traps, so your hack will even perform
better.
Q: Oh, well, thanks anyway. I always like to know as much as I can about the
PalmOS!
A: You're welcome. Happy hacking!
[EMAIL PROTECTED] on 01/12/2000 02:42:11 PM
Please respond to [EMAIL PROTECTED]
Sent by: [EMAIL PROTECTED]
To: [EMAIL PROTECTED]
cc: (Ryan Robertson/MTN/US/3Com)
Subject: Re: Palm Knowlege Base
I don't know if this palm-dev-forum posting showed up in your mailbox before you
sent out your question:
> I'm really hoping to have the KB, Creator ID pages, and Email Pages back up by
> Friday afternoon.
>
> Ryan Robertson
> Palm Development Support
-- Keith
"Bryan Nystrom" <[EMAIL PROTECTED]> on 01/12/2000 10:53:58 AM
Please respond to [EMAIL PROTECTED]
Sent by: "Bryan Nystrom" <[EMAIL PROTECTED]>
To: [EMAIL PROTECTED]
cc: (Keith Rollin/HQ/3Com)
Subject: Palm Knowlege Base
Anyone heard how much longer Palm expects the Knowledge Base to be down?
Anyone have a copy of the "Seeing Gray" article that they can send me?
Thanks!
