On Mon, 26 Feb 2001, Brian S. Julin wrote:
>
> 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.
Exactly.
> This is as complicated as a lot of people will want to get, so it
> is perfect in that way.
TNX.
> 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);
^^
Why double-pointer? Isn't a single pointer enough?
> 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.
I see! That makes it possible to use zbuffer, alpha-buffer and
texture-buffer at once.
> 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;
> void* res_subopts;
> size_t res_subopts_size;
I moved this into ggiResource_t to have opaque data handling.
To have access to multiple resources suggest to add these functions
as API:
ggiResource_t ggiGallocGetNextResource(ggiResource_t res);
int ggiGallocGetProperties(ggiResource_t res,
struct ResourceProperties *props);
> enum Resourcetype res_type;
> enum ResourceOption res_option;
> enum ResourceState res_state; /* Instead of GALLOC_MODIFIED error code */
> }
Done.
> 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;
> };
I moved ggi_mode mode into ggiResource as well.
ggiResource is internally defined:
------------------------------------------------------------
struct ggiResource {
/* next resource in this list */
struct ggiResource *next;
/* pointer to the first resource-element in this list */
struct ggiResource *first;
/* the properties of this resource */
struct ResourceProperties props;
/* The visual this resource contains to */
ggi_visual_t vis;
/* the mode of the visual */
ggi_mode mode;
void *res_subopts;
size_t res_subopts_size;
/* If the resource uses a directbuffer, then
* db points to it.
*/
ggi_directbuffer *db;
/* If the resource uses a system RAM buffer, then
* buf points to it.
*/
void *buf;
/* pointers to access the VRAM or directbuffer
*/
void *read;
void *write;
};
------------------------------------------------------------
[snip]
> > 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.
Hmmm... You are thinking in the same direction as I do. That's why I
asked, if it is ok.
Has anyone some suggestions for a clean namespace?
CU,
Christoph Egger
E-Mail: [EMAIL PROTECTED]
P.S.: I've attached the current API-header-file including the above
changes.
/*
******************************************************************************
LibGalloc: extension API header file
Copyright (C) 2001 Christoph Egger [[EMAIL PROTECTED]]
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
THE AUTHOR(S) BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
******************************************************************************
*/
#ifndef _GGI_GALLOC_H
#define _GGI_GALLOC_H
#include <ggi/ggi.h>
__BEGIN_DECLS
/* Extension management
*/
int ggiGallocInit(void);
int ggiGallocExit(void);
int ggiGallocAttach(ggi_visual_t vis);
int ggiGallocDetach(ggi_visual_t vis);
/* Structure
*/
#ifdef HAVE_STRUCT_GALLOC
typedef struct ggiResource *ggiResource_t;
#else
typedef void *ggiResource_t;
#endif
enum Resourcetype {
/* defined by extension */
RT_SUBTYPE_MASK = 0x00000fff,
RT_TYPE_MASK = 0x000ff000,
/* # of hardware "layers" */
RT_OVERLAY_MASK = 0x0ff00000,
/* hardware buffers mask */
RT_BUFFER_MASK = 0xf0000000,
/* generic drawing area in same format as the main fb */
RT_SWATCH = 0x00002000,
/* Right/left eye data */
RT_STEREO = 0x00003000,
/* Sprite/hw cursors */
RT_SPRITE = 0x00004000,
/* video */
RT_VIDEO = 0x00005000,
/* any window */
RT_WINDOW = 0x00006000,
/* e.g. feature connector */
RT_PASSTHRU = 0x00007000,
/* there is direct MMIO access to the feature's data */
RT_DIRECTBUFFER = 0x10000000,
/* Subtypes for sprite features */
RT_SPRITE_DONTCARE = 0x00000000,
/* Hardware pointer cursor */
RT_SPRITE_POINTER = 0x00000001,
/* Hardware text cursor */
RT_SPRITE_CURSOR = 0x00000002,
/* True sprite (a-la C-64) */
RT_SPRITE_SPRITE = 0x00000003,
/* Subtypes for video features */
RT_VIDEO_DONTCARE = 0x00000000,
/* motion video */
RT_VIDEO_MOTION = 0x00000010,
/* streaming video */
RT_VIDEO_STREAMING = 0x00000011,
/* Subtypes for window features */
RT_WINDOW_DONTCARE = 0x00000000,
/* YUV-Viewport */
RT_WINDOW_YUV = 0x00000020,
/* Subtypes of (direct)buffer types */
RT_BUFFER_DONTCARE = 0x00000000,
/* zbuffer */
RT_BUFFER_ZBUFFER = 0x00000030,
/* alpha-buffer */
RT_BUFFER_ABUFFER = 0x00000031,
/* stencil-buffer */
RT_BUFFER_SBUFFER = 0x00000032,
/* texture-buffer */
RT_BUFFER_TBUFFER = 0x00000033,
};
enum ResourceOption {
/* Doesn't matter if system memory or VRAM is used for
* resource-type.
*/
RO_DONTCARE = 0x00000000,
/* Force to use system memory */
RO_MEMORY = 0x00000001,
/* Force to use VRAM */
RO_VRAM = 0x00000002,
};
enum ResourceState {
RS_OK = 0x00000000,
RS_MODIFIED = 0x00000001,
RS_NORESET = 0x00000002,
};
struct ResourceProperties {
enum Resourcetype res_type;
enum ResourceOption res_option;
enum ResourceState res_state;
int width, height, depth;
};
/* GAlloc error-codes */
#include <ggi/errors.h>
#define GALLOC_OK GGI_OK
#define GALLOC_EUNAVAILABLE -1
/* API functions
*/
/* checks, if an object of the given properties is available.
* If not, then it fails else it allocates it with the given size.
*/
ggiResource_t ggiGAlloc(ggi_visual_t vis,
struct ResourceProperties *props);
/* checks, if an object of the given properties will work.
* If not, then the modified properties passed back should work.
* If NOTHING would work on the current target, then it returns
* GALLOC_EUNAVAILABLE.
*/
int ggiGallocCheck(ggi_visual_t vis,
struct ResourceProperties *in,
struct ResourceProperties *out);
/* free's the allocated area by ggiGAlloc
*/
int ggiGallocFree(ggiResource_t res);
/* Get the next resource from the same visual as they are
* internally linked together.
*/
ggiResource_t ggiGallocGetNextResource(ggiResource_t res);
/* Get properties from the resource
*/
int ggiGallocGetProperties(ggiResource_t res,
struct ResourceProperties *props);
__END_DECLS
#endif /* _GGI_GALLOC_H */
