Path: utzoo!mnetor!uunet!lll-winken!lll-tis!ames!pasteur!ucbvax!CORY.BERKELEY.EDU!dillon From: dillon@CORY.BERKELEY.EDU (Matt Dillon) Newsgroups: comp.sys.amiga.tech Subject: RESOURCES (as in disk-resources) Message-ID: <8805040914.AA24466@cory.Berkeley.EDU> Date: 4 May 88 09:14:56 GMT Sender: daemon@ucbvax.BERKELEY.EDU Lines: 236 I have been refining my ideas on disk resources. What you see below is the culmination of that (so far) in a preliminary document. I intend to implement this over the summer and into the fall semester. Side note: I think I'm going to add a 'read-only' flag and allow resources to be shared. That is, the pointer returned for certain resources will be allocated just once for that resource, even if many programs are request it. The resource goes away when all references go away. Side note II: If enough people fall in love with this, it will *replace* IFF. Why? Because Usage-Wise, it is much easier to deal with and is much more powerful. Enjoy, -Matt RESOURCE.DOC PRELIMINARY DOCUMENT. COMMENTS PLEASE! I'm interested in any and all comments on the matter, especially any ideas on 'standard' reserved structures (apart from those listed and those in the Amiga includes). GENERAL: In general, the main idea is to be able to specify all sorts of useful information, both for the program which uses the resources, and for the user to ALLOW HIM TO MODIFY the resources. IFF does not cut it, as you will soon see. A basic requirement is to remove ALL WORK from the application program which uses the resources. That is, the program should be able to simply GetRes(handle, "titlebitmap") and the call would return a completely resolved BitMap structure for use in its title screen. Structures which the programmer used to have to build by hand in static declarations can be made into resources and resolved automatically. As far as the application program is concerned, a resource has three components: (1) A RESOURCE NAME ... any name you care to apply to the resource (2) A STRUCTURE NAME The name of the top level structure defining this resource (3) The RETURNED POINTER .. what the program gets from GetRes(), a pointer to the top level structure which is completely resolved and possibly containing pointers to lower level structures. The application program specifies the RESOURCE NAME in GetRes(). It is safe to assume that the programmer knows the structure of his personal resources since he created them. A resource editor, on the other hand, should be able to edit ANY resource, and thus lower level calls are provided to get more information about a resource (such as its STRUCTURE NAME and STRUCTURE FORMAT). WildCard calls are also available. TECHNICAL: how: bitmask of search areas (0 highest priority). Usually -1 is specified. to/from: area # (0..3) area: 0 resources contained in this executable 1 specified resource file (default:procname.rsrc) 2 local.rsrc 3 reserved 4-31 reserved for now (huh?) handle = OpenResHandle() Open new resource handle. Multiple handles may be openned if you wish. CloseResHandle(handle) Close resource handle and remove ALL allocated resource information GetResError (handle) Get last error SetResFile (handle, filename, how) Set the resource file for area 1. ptr = GetRes (handle, resname , how) Return a pointer to the requested resource or NULL value = GetResValue (handle, resname , how) structures <= 8 bytes only. Instead of allocating space for this resource, assume it contains an integral value and return that value, allocating nothing. char ** = GetResList (handle, wildcard, how) char ** array, list of known resource names matching the */? wildcard name char ** = GetStrList (handle, wildcard, how) char ** array, list of known structures matching the */? wildcard name. char ** = GetResStrList(handle, strname, how) list of resource names which are of the specified structure format (by structure name) rinfo = GetResInfo (handle, resname, how) Get more detailed information about a resource sinfo = GetStrInfo (handle, strname, how) Get more detailed information about a structure FreeRes (handle, ptr/ptr*/rinfo/sinfo) Free various allocated items returned by other calls. bool = CreateRes (handle, rinfo, to, resolved) Create (add) a new resource. Two formats are allowed for the resource data: unresolved and resolved. E.G. GetRes() returns a resolved structure, GetResInfo() gives an unresolved structure. Certain types of resources, such as dynamic resources, can only be created via the GetResInfo() format (unresolved). bool = CreateStr (handle, sinfo, to) Create (add) a new structure def bool = DeleteRes (handle, resname, from) Delete some resource bool = DeleteStr (handle, strname, from) Delete some structure def. RESINFO: Resource Information. NOTE that the resource data block is for the entire structure of the resource, including all static sub-structures, all in one contiguous chunk (not placed in the proper memory types for the structures). [0] = resource name [1] = master structure name [2] = size of data [3] = ptr to resource data (not defined in this document) STRINFO: Information about a structure. Any referenced or subreferenced structures are included. All structure ID's are renumbered according to their entry #, starting at ID 1. [0] = # of entries. Each entry takes 2 array spots. [1] = master structure name [2] = structure format [3] = structure name [4] = structure format [5] = structure name [6] = structure format ... the structure format is not defined in this document. STRUCTURE FORMAT, GENERAL CAPABILITIES: Structure ID's are tagged in bits 15 and 14 as follows: 00 - embedded structure 01 - parent pointer (rest of ID not used) 10 - self pointer (rest of ID not used) 11 - child pointer An ID of 0 is valid only for tag 11: pointer to unknown structure This has been thought out, but is too complex to post at this stage. Only the resource-editor needs to deal with the format that describes a particular resource structure. A resource structure is either (1) statically sized or (2) dynamically sized .. i.e. same structure name can have different sizes i.e. string data. In the case of being dynamically sized, the format of the dynamic part of the structure is an array of the last 'type' in the structure definition. Each structure also has a longword specifying the type of memory it can be placed in. dynamic Example: A BitMap structure is a dynamic structure whos format is what you see in the include's but with only ONE plane pointer. The structure is sized to fit as many plane pointers as required. Another dynamic example: You want a resource which contains a pointer to, say, 32K of cleared memory. 32K of zero's would NOT exist in the physical file, but would be allocated when you request the resource (i.e. if you have MEMF_CLEAR in the flags for some structure, no space is actually allocated in the physical file). Apart from the header, A structure is made up solely of other structures ... a list of structure ID's which refer to children (pointers to other structures), embedded structures (e.g. Node structure heads an IO request), self pointers (e.g. initialized List structure), or parent pointers (e.g. your resource is a doubly linked list). The child pointer type 'pointer to another structure' is used to give a single resource the capability to generate an entire menu with all pointers resolved if you wish. Another example would be the capability to generate, say, a BitMap structure complete with data in CHIP. Recursive structures are also allowed, and a general means of terminating a recursive structure is provided. RESERVED STRUCTURE NAMES: Please limit name length to <64 bytes. void no storage, always has ID of 0. byte or char 8 bit signed value word or short 16 bit signed value long 32 bit signed value ubyte 8 bit unsigned value uword 16 bit unsigned value ulong 32 bit unsigned value ffp 32 bit fast floating pt number ieee 64 bit IEEE floating pt number version short, version # revision short, revision # revdate revision date idstring dynamic storage, identification string author dynamic storage, author(s) of program copyright dynamic storage, copyright notice comment dynamic storage, textual comment expert ubyte expert mode 0..255 (0 = dumb user) give me some more names to reserve!!!