On Thu, 1 Mar 2001, Brian S. Julin wrote:
>
> On Thu, 1 Mar 2001, Christoph Egger wrote:
> > > You mean, when a VRAM resource is allocated, that we give it an ID number,
> > > and then you can ask for a second "engine" for the resource using that
> > > ID number somehow? How do you attach one "engine" to multiple VRAM
> > > resources using that API?
> >
> > See:
> >
> > > > To do this, libGAlloc can do some journalling things about
> > > > already _allocated_ resources with their properties.
> > >
> > > Yes, libGAlloc would maintain a target-specific data structure
> > > LIBGGI_GALLOCEXT(vis), that contains state about what's currently
> > > allocated.
> >
> > Exactly. Reading a bit further before commenting gives the answer to
> > some questions. :)
>
> No, this was clear. What was bothering me was that one resource
> could refer to another, which could make implementing GAlloc very hairy.
> But I see this is going to be necessary anyway, because I just read
> your last sample header more closely.
Have a look at the current API (it is attached) and rethink this:
> When you took the Z-buffer/Alpha enums and moved them to a subtype of
> a type, instead of bitflags, that was a good move, because the res_type was
> getting crowded anyway and it is bad to have an ALPHA API with a crowded
> field :)
>
> But this means to figure out what resource the Z-buffer or Alpha belongs
> to (usually but not always the main framebuffer) we will have to have these
> refer to another resource. I have proposed some stuff to help this below,
> but let us try to keep such references 1-deep, OK?
ok.
> > > Hmm... I'm not sold on that yet... definitely there should be a
> > > very simple way to use BSE, but then I think if you're sharing
> > > resources, a slightly less simple API might be fine, where you
> > > request a "set" of X DMA/AGP buffers, Y VRAM buffers, and Z
> > > engines, and you have a function to point the engines at the VRAM
> > > buffers and to transfer between DMA/AGP RAM, VRAM, and any VM
> > > buffers (allocate those separately since they always must work.)
> >
> > I don't think so. We can keep the API, when the properties-structure
> > is well-defined.
>
> I will wait to be convinced, then :).
*grin* The last API I attached is rather obselete. I refer the
current API I have on my disk. Sorry, I won't mislead you.
I have attached the current one.
BTW: It is in a compiling state.
> > I think, using an additional flag in res_type is enough to let the
> > target know everything to handle the resource.
>
> I am totally braindead -- obviously these belonged in the new
> res_opt feild. How does the following feel to you:
Ah... yes, right you are.
> enum GA_Storage_type {
>
> /* Doesn't matter how the resource is stored. */
> GA_STORAGE_DONTCARE = 0x00000000,
>
> /* On disk or other slow device. */
> GA_STORAGE_SECONDARY = 0x00000001,
>
> /* Offboard storage in swap or RAM. */
> GA_STORAGE_VIRT = 0x00000002,
>
> /* Data is stored in a physical RAM buffer */
> GA_STORAGE_RAM = 0x00000004,
>
> /* capable of hardware accelerated transfer to the card */
> GA_STORAGE_TRANSFER = 0x00000008,
>
> /* capable of MMIO or other direct random access */
> GA_STORAGE_DIRECT = 0x00000010,
>
> /* Onboard storage -- data is on the other side of the BUS */
> GA_STORAGE_VRAM = 0x00000020,
>
> GA_STORAGE_READONLY = 0x00000040,
> GA_STORAGE_COPYONWRITE = 0x00000080,
>
> /* This isn't storage, it's something that uses or consumes
> the resource. */
> GA_STORAGE_ENGINE = 0x10000000
> }
>
> /* Behavior control information between Galloc/higher level. */
> enum GA_resource_state {
> /* Bits that are used to talk to Galloc */
> GA_STATE_REQUEST_MASK 0x00000013,
> /* Bits Galloc uses to talk back to caller. */
> GA_STATE_RESPONSE_MASK 0x0000001c,
>
> /* This resource is in-service and must not be disturbed. */
> GA_STATE_NORESET = 0x00000001,
> /* Don't bother modifying this resource, if it fails as is, it fails.*/
> GA_STATE_NOCHANGE = 0x00000002,
>
> /* This resource request was altered due to failure or GGI_AUTO */
> GA_STATE_MODIFIED = 0x00000004,
> /* This resource request failed. */
> GA_STATE_FAILED = 0x00000008,
>
> /* This resource modifies or refers to the last resource in the
> list that did not have this flag set. */
> GA_STATE_SEEABOVE 0x00000010,
> };
>
> struct GA_ResourceProperties {
> enum GA_resource_type rtype;
> enum GA_storage_type storage_need, storage_ok;
> enum GA_resource_state rstate;
> [...]
Looks very good. I have merged that in my current API-file and
modified them a bit.
> > P.S.: Hey list! This discussion is NOT intended to be a private one
> > between Brian and me! :) You can give arguements as well!
>
> Please... Chris and I are going to actually start getting sick
> of each other soon :). At least someone else say that they are
> following and we haven't just created some confusing mush that
> noone but us will ever understand...
Yep. Even when someone just gives something like a "beep" ... :-)
> Chris -- If I send you a sample but "working" implementation of GAlloc
> based on the current discussion tonight, but with feature-specific
> resource structures, would that help sell you on the idea?
A lot, if you do your work on my work. I am sending you a tar-ball in
a personal mail.
CU,
Christoph Egger
E-Mail: [EMAIL PROTECTED]
/*
******************************************************************************
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 ggiGAInit(void);
int ggiGAExit(void);
int ggiGAAttach(ggi_visual_t vis);
int ggiGADetach(ggi_visual_t vis);
/* Structure
*/
#ifdef HAVE_STRUCT_GALLOC
typedef struct ggiGA_resource *ggiGA_resource_t;
#else
typedef void *ggiGA_resource_t;
#endif
enum GA_resource_type {
/* defined by extension */
GA_RT_SUBTYPE_MASK = 0x00000fff,
GA_RT_TYPE_MASK = 0x000ff000,
/* # of hardware "layers" */
GA_RT_OVERLAY_MASK = 0x0ff00000,
/* hardware buffers mask */
GA_RT_BUFFER_MASK = 0xf0000000,
/* */
GA_RT_FRAME = 0x00001000,
/* generic drawing area in same format as the main fb */
GA_RT_SWATCH = 0x00002000,
/* Right/left eye data */
GA_RT_STEREO = 0x00003000,
/* Sprite/hw cursors */
GA_RT_SPRITE = 0x00004000,
/* video */
GA_RT_VIDEO = 0x00005000,
/* any window */
GA_RT_WINDOW = 0x00006000,
/* e.g. feature connector */
GA_RT_PASSTHRU = 0x00007000,
/* there is direct MMIO access to the feature's data */
GA_RT_DIRECTBUFFER = 0x10000000,
/* Subtypes for sprite features */
GA_RT_SPRITE_DONTCARE = 0x00000000,
/* Hardware pointer cursor */
GA_RT_SPRITE_POINTER = 0x00000001,
/* Hardware text cursor */
GA_RT_SPRITE_CURSOR = 0x00000002,
/* True sprite (a-la C-64) */
GA_RT_SPRITE_SPRITE = 0x00000003,
/* Subtypes for video features */
GA_RT_VIDEO_DONTCARE = 0x00000000,
/* motion video */
GA_RT_VIDEO_MOTION = 0x00000010,
/* streaming video */
GA_RT_VIDEO_STREAMING = 0x00000011,
/* Subtypes for window features */
GA_RT_WINDOW_DONTCARE = 0x00000000,
/* YUV-Viewport */
GA_RT_WINDOW_YUV = 0x00000020,
/* Subtypes of (direct)buffer types */
GA_RT_BUFFER_DONTCARE = 0x00000000,
/* zbuffer */
GA_RT_BUFFER_ZBUFFER = 0x00000030,
/* alpha-buffer */
GA_RT_BUFFER_ABUFFER = 0x00000031,
/* stencil-buffer */
GA_RT_BUFFER_SBUFFER = 0x00000032,
/* texture-buffer */
GA_RT_BUFFER_TBUFFER = 0x00000033,
};
enum GA_storage_type {
/* Doesn't matter how the resource is stored. */
GA_STORAGE_DONTCARE = 0x00000000,
/* On disk or other slow device. */
GA_STORAGE_SECONDARY = 0x00000001,
/* Offboard storage in swap or RAM. */
GA_STORAGE_VIRT = 0x00000002,
/* Data is stored in a physical RAM buffer */
GA_STORAGE_RAM = 0x00000004,
/* capable of hardware accelerated transfer to the card */
GA_STORAGE_TRANSFER = 0x00000008,
/* capable of MMIO or other direct random access */
GA_STORAGE_DIRECT = 0x00000010,
/* Onboard storage -- data is on the other side of the BUS */
GA_STORAGE_VRAM = 0x00000020,
/* Readonly resource - means you can e.g. set an image to a sprite,
* so it has at least one, but that's it!
*/
GA_STORAGE_READONLY = 0x00000040,
/* The resource has to be copyied before writing. This is i.e.
* necessary, when you share the resource with an read-only one.
*/
GA_STORAGE_COPYONWRITE = 0x00000080,
/* This isn't storage, it's something that uses or consumes
* the resource.
*/
GA_STORAGE_ENGINE = 0x10000000,
};
/* Behavior control information between Galloc/higher level. */
enum GA_resource_state {
/* Bits that are used to talk to Galloc */
GA_STATE_REQUEST_MASK = 0x00000013,
/* Bits Galloc uses to talk back to caller. */
GA_STATE_RESPONSE_MASK = 0x0000001C,
/* This resource is in-service and must not be disturbed. */
GA_STATE_NORESET = 0x00000001,
/* Don't bother modifying this resource, if
* it fails as is, it fails.
*/
GA_STATE_NOCHANGE = 0x00000002,
/* This resource request was altered due to
* failure or GGI_AUTO
*/
GA_STATE_MODIFIED = 0x00000004,
/* This resource request failed. */
GA_STATE_FAILED = 0x00000008,
/* This resource modifies or refers to the last
* resource in the list that did not have this flag set.
*/
GA_STATE_SEEABOVE = 0x00000010,
/* This resource _is_ shared!
* NEVER set it - only libGAlloc does this!
*/
GA_STORAGE_SHARED = 0x00000020,
};
struct GA_ResourceProperties {
enum GA_resource_type res_type;
enum GA_storage_type storage_need, storage_ok;
enum GA_resource_state res_state;
/* common attributes of a resource */
int width, height; /* have to be filled out */
ggi_graphtype depth; /* have only to be filled out, if required */
/* resource-specific options */
void *res_subopts;
size_t res_subopts_size;
};
/* GAlloc error-codes */
#include <ggi/errors.h>
#define GALLOC_OK GGI_OK
#define GALLOC_EUNAVAILABLE -1
/* This means, that the resource wasn't specified enough
* for the target to handle. This should never happen, when
* the caller has the resource specified enough.
*/
#define GALLOC_SPECIFY -2
/* API functions
*/
/* clears up the request list and frees the allocated memory
*/
int ggiGAEmptyRequestList(ggiGA_resource_t *reqlist);
/* add a new request to the request list for a new resource with the
* given properties. It returns also the request-ID to get access to it later.
*/
int ggiGAAddRequest(ggiGA_resource_t *reqlist,
struct GA_ResourceProperties *props, int *req_id);
/* special function for requesting a graph/text-mode. Use it instead of
* ggiGAAddRequest() to request any mode.
*/
int ggiGAAddSimpleMode(ggiGA_resource_t *reqlist, ggi_mode *mode, int *req_id);
/* checks, if the requested resources with the given properties will work.
* If not, then the modified result passed back should work.
* If NOTHING would work on the current target, then it returns
* GALLOC_EUNAVAILABLE. If GALLOC_SPECIFY is returned, then one resource
* is not specified enough to be handled by the current target.
*/
int ggiGACheck(ggi_visual_t vis, ggiGA_resource_t request,
ggiGA_resource_t *result);
int ggiGASet(ggi_visual_t vis, ggiGA_resource_t request,
ggiGA_resource_t *result);
#define ggiGAGet(vis, result) ggiGACheck(vis, NULL, result);
/* returns the current properties of the resource with the given req_id.
* returns NULL, if the req_id is not valid.
*/
struct GA_ResourceProperties *ggiGAGetProperties(ggiGA_resource_t res,
int req_id);
/* returns a pointer of the requested resource given by the req_id .
* returns NULL, if the req_id is not valid.
*/
void *ggiGATieResource(ggiGA_resource_t res, int req_id);
/* Releases the resource with the given request-ID.
*/
int ggiGAUntieResource(ggiGA_resource_t *res, int req_id);
__END_DECLS
#endif /* _GGI_GALLOC_H */
