Re: Q3Object_GetValue/SetValue API

[Joseph J. S. <jo...@st...>]

At 7:00 PM -0700 6/1/04, James W. Walker wrote:

>I have written, but not checked in, the following APIs.  They are a 
>bit simpler than, say, Apple's property APIs, in that there is only 
>one property tag rather than a creator and a type.  IMHO, a single 
>type is enough, and it made it possible to implement the feature 
>fairly easily using E3HashTable.  Is this acceptable?

Well, you're mixing "type" (which to mean means something like 
TQ3Uns32, TQ3SInt16, TQ3Boolean, etc.) with "property" (which would 
be something like, "leave the depth buffer uncleared when 
rendering").  That means, if we decide that a particular property 
should be a TQ3Boolean, but later realize we need three values 
instead of two, we're stuck.  If we use both a type and a property 
identifier, then we can change the type under the hood, as long as we 
provide automatic conversion (or at least graceful failure) to/from 
whatever type the client code is specifying.

All that said, I think I'm OK with mixing these two concepts 
together.  We can make it clear by naming our "property type tags" 
with both property identifier and type, e.g., 
kQ3ClearDepthBufferBoolean, or kQ3RenderFlagsUns32.  That way, users 
of the code know what data type to pass and return (important, since 
a four-byte TQ3Uns32 is *not* identical to an arbitrary 4-byte 
buffer, due to endianness issues).  And if we ever need to change the 
type of a particular property, we can do so by just defining a new 
property type tag, but continuing to support the old one.

On the actual APIs: I don't think we need Q3Object_GetPropertySize. 
Instead, why not follow what Apple's doing with most of their newer 
APIs: allow Q3Object_GetProperty to take a null 'buffer' parameter, 
but still stuff the size into the actualSize parameter.  So, when 
unsure of the needed size, you call Q3Object_GetProperty once to get 
the data size, then allocate your buffer, and call it again to get 
the actual data.  (In most cases I don't think you'll need to ask the 
size anyway, since it will be clearly implied by the property type.)

>In case anyone is about to object that it would be nice to 
>distinguish between properties defined by Quesa and user-defined 
>properties, we could use a convention like Apple's, that property 
>tags consisting of all lowercase letters are reserved for official 
>Quesa use.

Yes, that sounds fine to me.

-- 
,------------------------------------------------------------------.
|    Joseph J. Strout         Check out the Mac Web Directory:     |
|    jo...@st...           http://www.macwebdir.com/            |
`------------------------------------------------------------------'