On Mon, 26 Feb 2001, Christoph Egger wrote:
> Now I have worked out an API for libGalloc. It is attached.
> Any further suggestions?
It looks good for everyday use (which is the most important
part :). The functions you have defined there now would be
called after the video mode is set and would fail if they
cannot get the feature without changing the video mode. This
is as complicated as a lot of people will want to get, so
it is perfect in that way.
I think I see what you are trying to do with the params, but
it seems to me to be a bit awkward, though:
int ggiGallocCheck(ggi_visual_t vis,
struct ResourceProperties *props,
int width, int height);
...so the width and height are read-only params, and if they
needed to be modified, the new values are put in props->width
and props->height? It's kinda strange to have just the width,
height in the function param list; usually either you have
a convenience function that breaks out all the structure values,
like so:
/*
(a la ggiCheckSimpleMode.)
The problem with doing it this way is that if you change
the struct, then you find yourself wanting to change the
function params. Good for end-user API convenience functions. */
int ggiGallocCheck(ggi_visual_t vis, Resourcetype res_type,
ResourceOption res_option, int width, int height, int depth
struct ResourceProperties *readback);
or, you keep things inside the structure like so:
/* This way if we add any members to the struct, old code
will still compile and run. Also, you get a new, modified copy
of the resource properties in out, which saves you having
to copy it yourself to keep it from getting trounced.
This design is better for Intraface, in places where
mere mortals rarely tread. LibGalloc qualifies as that,
so don't spend time trying to make the "API" userfriendly. */
int ggiGallocCheck(ggi_visual_t vis,
struct ResourceProperties *in,
struct ResourceProperties **out);
There are certain cases where feature-specific properties will
have to get down to this level even if the levels above them
have chewed on them. You can't expect GallocCheck to be able
to tell LibOVL whether it can give LibOVL a sprite that has
transparancy on a certain video card or not, if all LibOVL asks
LibGalloc is "can I have a sprite?", not "can I have a sprite with
transparency?". Libraries like LibOVL should try as best they
can to keep bloat out of Galloc, but there is no way that they
can distill the features down to a few integer values in every single
case.
Also, give the "resources" a *next member to hang a linked list on.
This will be needed later when we add functions to negotiate
multiple features and negotiate them against the video mode.
so that ends up being:
/* We could do it this way, or use unions, either way we are stuck
with keeping track of res_subopts_size so we can copy resource
properties even if we do not know/care how to examine them. */
struct ResourceProperties {
struct ResourceProperties *next;
enum Resourcetype res_type;
enum ResourceOption res_option;
enum ResourceState res_state; /* Instead of GALLOC_MODIFIED error code */
void* res_subopts;
size_t res_subopts_size;
}
I'd see three actual internal functions (_ggigalloccheck, _ggigallocset,
_ggigallocget) at the core of libGalloc, which would have to be
implemented for each target. Implementing ggiGallocCheck would
look like this, using those internal functions:
struct ModeProperties {
struct ResourceProperties res;
ggi_mode mode;
};
/* Simple single feature check against current mode */
int ggiGallocCheck(ggi_visual_t vis,
struct ResourceProperties *in,
struct ResourceProperties **out)
{
struct ModeProperties this;
if (in->next == NULL) GGI_DEBUG(
"Simple resource check called with list of multiple features");
if(in->res_type & RT_TYPE_MASK == RT_FRAME) GGI_DEBUG(
"Simple resource check called on a main mode placeholder");
/* Put the current mode at the top of the desired feature list. */
ggiGalloc_Mode2RT(ggi_visual_t vis, &this);
if(this->res.res_type & RT_TYPE_MASK != RT_FRAME) GGI_DEBUG(
"Couldn't make resource from mode (mode not set yet?)");
this->res.next = in;
/* Insist that the features be available without calling SetMode
again, even if the main mode isn't changed. */
this->res.res_state = RS_NORESET;
return(_ggigalloccheck(vis, &this, out));
}
> Is the namespace ok?
Actually, the "resource" thing will probably be confused
with the ggiResourceAquire() function which is used to
grab a directbuffer away from the accelerator engine.
there is already a ggi_resource_t, which is awfully close
to ggiResource_t.
The RT_* stuff might end up clashing with "Real-Time"
support libraries at some point, but that's not too horribly
likely.
--
Brian
