Fresh Fish 8

home *** CD-ROM | disk | FTP | other *** search

/ Fresh Fish 8 / FreshFishVol8-CD2.bin / bbs / gfx / superview-lib-9.12.lha / SuperView-Lib / Programmers / Docs / SVSupport_Ref_ENG.doc < prev

Wrap

Text File | 1994-12-28 | 37.6 KB | 1,599 lines

$VER: SVSupport_Reference.doc V6.2 (14.12.94) © 1994 by Andreas R. Kleinert. All rights reserved. - Feel free to translate this Doc-File into other languages. - Andreas R. Kleinert, Grube Hohe Grethe 23, D-57074 Siegen, Germany. Phone: +49-271-331859 (weekdays after 18.00h) +49-271-332147 (weekdays after 18.00h) EMail: Fido Andreas Kleinert 2:2457/435.10 Usenet/InterNet Andreas_Kleinert@superview.ftn.sub.org If nothing else works, try one of these Fido-InterNet gateways: Andreas_Kleinert@p10.f435.n2457.z2.fido.sub.org (Germany) Andreas_Kleinert@p10.f435.n2457.z2.fidonet.org (US) Here is a listing of all currently available functions of the superviewsupport.library in an Autodoc-like style of description : SVSUP_GetMemList ; since Version 1 SVSUP_FreeMemList SVSUP_AddMemEntry SVSUP_AllocMemEntry SVSUP_CheckInterleaved SVSUP_GetXAspect SVSUP_GetYAspect SVSUP_GetBitMapDepth SVSUP_GetBitMapHeight SVSUP_GetBodySize SVSUP_GetStdScreenSize SVSUP_GetBestModeID SVSUP_CopyScreenToBuffer8 *** OBSOLETE : Use ScreenToOnePlane8 SVSUP_LoadControlPad ; since Version 2 SVSUP_SaveControlPad SVSUP_FreeControlPad SVSUP_FindControlPad SVSUP_BitPlaneToOnePlane8 ; since Version 3 SVSUP_OnePlaneToBitPlane8 SVSUP_ScreenToOnePlane8 SVSUP_ScreenToBitPlane8 SVSUP_DisplayGfxBuffer ; since Version 4 SVSUP_UnDisplayGfxBuffer SVSUP_FreeGfxBuffer SVSUP_FindControlPadNoCase ; since Version 5 SVSUP_ModifyControlPad SVSUP_AddControlPad SVSUP_AllocVMemEntry ; since Version 6 SVSUP_AccessVMemEntry SVSUP_ReleaseVMemEntry SVSUP_ReadVMemBytes SVSUP_WriteVMemBytes SVSUP_VecToVMemEntry SVSUP_GetVMemSize ----------------------------------------------------------------------------- Functions available since Version 1 : ----------------------------------------------------------------------------- NAME SVSUP_GetMemList SYNOPSIS APTR SVSUP_GetMemList(void) D0 -$1e FUNCTION Allocates a handle for accessing a memory allocation list. INPUT(S) - RESULT A pointer to a new allocated Handle or NULL, if allocation failed. WARNING Test, if the result was NULL, or not ! BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO SVSUP_FreeMemList ----------------------------------------------------------------------------- NAME SVSUP_FreeMemList SYNOPSIS VOID SVSUP_FreeMemList(APTR handle) D0 -$24 A1 FUNCTION Frees all memory from the given memory allocation list and also delocates the list itself ! INPUT(S) handle - a valid handle RESULT - SINCE ... version 1 of the superviewsupport.library. SEE ALSO SVSUP_GetMemList ----------------------------------------------------------------------------- NAME SVSUP_AddMemEntry SYNOPSIS ULONG SVSUP_AddMemEntry(APTR handle, APTR pointer) D0 -$2a A1 A2 FUNCTION Adds an "AllocVec"ed memory pointer to the memory list, to be remembered for delocation later. INPUT(S) handle - a valid handle pointer - a pointer to a chunk of memory, which has been allocated with Exec's AllocVec() function RESULT Boolean value : The memory will be freed immediately, if remembering failed. BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO SVSUP_FreeMemList ----------------------------------------------------------------------------- NAME SVSUP_AllocMemEntry SYNOPSIS APTR SVSUP_AllocMemEntry(APTR handle, size, type) D0 -$30 A1 D0 D1 FUNCTION Allocates memory just like AllocVec(), but remembers this in the given memory allocation list. INPUT(S) handle - a valid handle size - needed size for the memory chunk type - "MEMF_"-specification of the memory type RESULT pointer to memory or NULL. BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO SVSUP_GetMemList, SVSUP_FreeMemList ----------------------------------------------------------------------------- NAME SVSUP_CheckInterleaved SYNOPSIS ULONG SVSUP_CheckInterleaved(struct Screen *sc) D0 -$36 A1 FUNCTION Is the BitMap of the given Screen of type "interleaved" (possible since OS V39 with AGA) ? INPUT(S) sc - a valid Screen Pointer RESULT Boolean value. BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO - ----------------------------------------------------------------------------- NAME SVSUP_GetXAspect SYNOPSIS UBYTE SVSUP_GetXAspect(struct Screen *sc) D0 -$3c A1 FUNCTION Calculates an ILBM compatible XAspect-value for any ScreenMode. INPUT(S) sc - a valid Screen Pointer RESULT XAspect value for the given Screen. BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO SVSUP_GetXAspect ----------------------------------------------------------------------------- NAME SVSUP_GetYAspect SYNOPSIS UBYTE SVSUP_GetYAspect(struct Screen *sc) D0 -$42 A1 FUNCTION Calculates an ILBM compatible YAspect-value for any ScreenMode. INPUT(S) sc - a valid Screen Pointer RESULT YAspect value for the given Screen. BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO SVSUP_GetXAspect ----------------------------------------------------------------------------- NAME SVSUP_GetBitMapDepth SYNOPSIS ULONG SVSUP_GetBitMapDepth(struct Screen *sc) D0 -$48 A1 FUNCTION Finds out the depth of the BitMap of a given Screen. This is safer than accessing the various structures under V39+. INPUT(S) sc - a valid Screen Pointer RESULT depth of the Screen's BitMap. BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO SVSUP_GetBitMapHeight ----------------------------------------------------------------------------- NAME SVSUP_GetBitMapHeight SYNOPSIS ULONG SVSUP_GetBitMapHeight(struct Screen *sc) D0 -$4e A1 FUNCTION Finds out the height of the BitMap of a given Screen. This is safer than accessing the various structures under V39+. INPUT(S) sc - a valid Screen Pointer RESULT height of the Screen's BitMap. BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO SVSUP_GetBitMapDepth ----------------------------------------------------------------------------- NAME SVSUP_GetBodySize SYNOPSIS ULONG SVSUP_GetBodySize(struct Screen *sc) D0 -$54 A1 FUNCTION This function calculates the size of a buffer to hold the given Screen's BitMap. As the name reflects, this buffer confirms to the needs of a "BODY" (or ABIT) chunk for ILBM (or ACBM) Files. No alignment things are done. INPUT(S) sc - a valid Screen Pointer RESULT NULL or an adequate SVERR-Errorcode. BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO - ----------------------------------------------------------------------------- NAME SVSUP_GetStdScreenSize SYNOPSIS ULONG SVSUP_GetStdScreenSize(ULONG mode_id, ULONG *width, D0 -$5a D0 A1 ULONG *height) A2 FUNCTION Gets the standard dimensions for a given ScreenMode. For e.g. "PAL:HighRes", this would be 640 and 256. The values are written into the supplied ULONGs. This function may FAIL ! INPUT(S) sc - a valid Screen Pointer RESULT Boolean value. BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO SVSUP_SuperView ----------------------------------------------------------------------------- NAME SVSUP_GetBestModeID SYNOPSIS ULONG SVSUP_GetBestModeID(ULONG width, ULONG height, ULONG depth) D0 -$60 D0 D1 D2 FUNCTION Returns the best ScreenMode ID for a hypothetical Screen with the given dimensions. Under V37 ECS is assumed, under V39 the appropriate Gfx-Library's function is used for that. INPUT(S) width, height, depth - Screen dimension values RESULT a ModeID value. BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO - ----------------------------------------------------------------------------- NAME SVSUP_CopyScreenToBuffer8 *** OBSOLETE : Use ScreenToOnePlane8 SYNOPSIS ULONG SVSUP_CopyScreenToBuffer8(struct Screen *sc, UBYTE *buffer, D0 -$66 A1 A2 ULONG width, ULONG height, D0 D1 ULONG depth) D2 FUNCTION *** You should use SVSUP_ScreenToOnePlane8() instead, which is more easy to handle and uses this function, anyway ... This function copies the content of a common Intuition Screen into a buffer in the "ChunkyPixel" (8 Bit) format. The buffer itself (with size = width * height) has to be supplied. The width, height and depth values (depth must be smaller than 8) have to be supplied also. These are not read from the Screen. This function may FAIL. INPUT(S) sc - a valid ScreenPointer buffer - a pointer to a buffer with size = width * height width - Screen's Width height - Screen's Height depth - Screen's Depth RESULT Boolean value. BUGS - SINCE ... version 1 of the superviewsupport.library. SEE ALSO SVSUP_SuperWrite ----------------------------------------------------------------------------- Functions available since Version 2 : ----------------------------------------------------------------------------- NAME SVSUP_LoadControlPad SYNOPSIS ULONG SVSUP_LoadControlPad(UBYTE *filename, struct SV_ControlPad **pad) D0 -$6c A1 A2 FUNCTION Opens and reads a standard Configuration File for superview.library's SVObjects, SVDrivers, etc. It consists of Tooltype-like entries in the form : <Name>=<Content> or <Keyword>, where each entry is built of one line of the file. All lines beginning with "/" or ";" or just blank lines are handled as comments and are ignored. All ControlPads are chained in a single-linked List. Remember to save the head-pointer to the List somewhere, because it's needed for free'ing the List. Only READ-ACCESSES should be done to the list entries, but if you want to add more entries to the list, note that all entries have to be allocated with AllocVec() and delocated with FreeVec(). INPUT(S) filename - a FileName for AmigaDOS pad - a pointer to a ControlPad-Structure pointer RESULT Boolean value. If the function returned FALSE, pad will also be NULL. BUGS SVSUP_FindControlPad, SVSUP_SaveControlPad, SVSUP_FreeControlPad SINCE ... version 2 of the superviewsupport.library. SEE ALSO - ----------------------------------------------------------------------------- NAME SVSUP_SaveControlPad SYNOPSIS ULONG SVSUP_SaveControlPad(UBYTE *filename, struct SV_ControlPad *pad) D0 -$72 A1 A2 FUNCTION Writes a standard Configuration File for superview.library's SVObjects, SVDrivers, etc. You have to supply your own ControlPad-List (or one supplied from SVSUP_LoadControlPad). INPUT(S) filename - a FileName for AmigaDOS pad - a pointer to a ControlPad-Structure (List-Head) RESULT Boolean value. BUGS - SINCE ... version 2 of the superviewsupport.library. SEE ALSO SVSUP_FindControlPad, SVSUP_LoadControlPad, SVSUP_FreeControlPad ----------------------------------------------------------------------------- NAME SVSUP_FreeControlPad SYNOPSIS ULONG SVSUP_FreeControlPad(struct SV_ControlPad *pad) D0 -$78 A1 FUNCTION Frees a single-chained list of ControlPads, which has been allocated and initialized via SVSUP_LoadControlPad() before. If you want to free your own, self-created ControlPad lists, note that all entries have to be allocated with AllocVec() and delocated with FreeVec(). INPUT(S) pad - a pointer to a ControlPad-Structure (List-Head) RESULT Boolean value. (returns FALSE when pad is a NULL pointer) BUGS - SINCE ... version 2 of the superviewsupport.library. SEE ALSO SVSUP_FindControlPad, SVSUP_SaveControlPad, SVSUP_LoadControlPad ----------------------------------------------------------------------------- NAME SVSUP_FindControlPad SYNOPSIS ULONG SVSUP_FindControlPad(struct SV_ControlPad *pad, D0 -$7e A1 UBYTE *name, A2 UBYTE **content) A3 FUNCTION A ControlPad-List consists of Tooltype-like entries in the form : <Name>=<Content> or <Keyword>. This function scans through such a list and searches for the Content of an Entry with a specific name. For Keywords the result is TRUE, but the Content pointer will be NULL nevertheless. Searching IS case-sensitive ! Only READ-ACCESS to the content is allowed. INPUT(S) pad - a pointer to a ControlPad-Structure (List-Head) name - the name of the entry to search for content - a pointer to a string pointer (the string pointer will be initialized with a pointer to the Content or NULL) RESULT Boolean value. BUGS - SINCE ... version 2 of the superviewsupport.library. SEE ALSO SVSUP_LoadControlPad, SVSUP_SaveControlPad, SVSUP_FreeControlPad ----------------------------------------------------------------------------- Functions available since Version 3 : ----------------------------------------------------------------------------- NAME SVSUP_BitPlaneToOnePlane8 SYNOPSIS ULONG SVSUP_BitPlaneToOnePlane8(struct SV_GfxBuffer *gfxb, D0 -$84 A1 struct SV_GfxBuffer **destgfxb) A2 FUNCTION This function takes a GfxBuffer of type BITPLANE and creates a GfxBuffer of type ONEPLANE out of it. This works with upto 8 Bit ColorDepth (256 Colors). The new GfxBuffer has to be given free by the user. INPUT(S) gfx - a pointer to the Source GfxBuffer (BITPLANE) destgfx - a pointer to a pointer for the Destination GfxBuffer (ONEPLANE) RESULT NULL or a SVERR-Errorcode. BUGS - SINCE ... version 3 of the superviewsupport.library. SEE ALSO SVSUP_OnePlaneToBitPlane8 ----------------------------------------------------------------------------- NAME SVSUP_OnePlaneToBitPlane8 SYNOPSIS ULONG SVSUP_OnePlaneToBitPlane8(struct SV_GfxBuffer *gfxb, D0 -$8a A1 struct SV_GfxBuffer **destgfxb) A2 FUNCTION This function takes a GfxBuffer of type ONEPLANE and creates a GfxBuffer of type BITPLANE out of it. This works with upto 8 Bit ColorDepth (256 Colors). The new GfxBuffer has to be given free by the user. INPUT(S) gfx - a pointer to the Source GfxBuffer (ONEPLANE) destgfx - a pointer to a pointer for the Destination GfxBuffer (BITPLANE) RESULT NULL or a SVERR-Errorcode. BUGS - SINCE ... version 3 of the superviewsupport.library. SEE ALSO SVSUP_BitPlaneToOnePlane8 ----------------------------------------------------------------------------- NAME SVSUP_ScreenToOnePlane8 SYNOPSIS ULONG SVSUP_ScreenToOnePlane8(struct Screen *sc, D0 -$90 A1 struct SV_GfxBuffer **destgfxb) A2 FUNCTION This function takes an Intuition Screen and creates a GfxBuffer of type ONEPLANE out of it. This works with upto 8 Bit ColorDepth (256 Colors). The new GfxBuffer has to be given free by the user. INPUT(S) gfx - a pointer to an Intuition Screen destgfx - a pointer to a pointer for the Destination GfxBuffer (ONEPLANE) RESULT NULL or a SVERR-Errorcode. BUGS - SINCE ... version 3 of the superviewsupport.library. SEE ALSO SVSUP_ScreenToBitPlane8 ----------------------------------------------------------------------------- NAME SVSUP_ScreenToBitPlane8 SYNOPSIS ULONG SVSUP_ScreenToBitPlane8(struct Screen *sc, D0 -$96 A1 struct SV_GfxBuffer **destgfxb) A2 FUNCTION This function takes an Intuition Screen and creates a GfxBuffer of type BITPLANE out of it. This works with upto 8 Bit ColorDepth (256 Colors). The new GfxBuffer has to be given free by the user. INPUT(S) gfx - a pointer to an Intuition Screen destgfx - a pointer to a pointer for the Destination GfxBuffer (BITPLANE) RESULT NULL or a SVERR-Errorcode. BUGS - SINCE ... version 3 of the superviewsupport.library. SEE ALSO SVSUP_ScreenToOnePlane8 ----------------------------------------------------------------------------- Functions available since Version 4 : ----------------------------------------------------------------------------- NAME SVSUP_DisplayGfxBuffer SYNOPSIS ULONG SVSUP_DisplayGfxBuffer(struct SVSUP_DisplayHandle *disphandle) D0 -$9c A1 FUNCTION This function allows displaying of GfxBuffers, e.g. for test-purposes. This will may you, if you simply want to check the results of self-created GfxBuffers or compare the results of a GfxBuffer-conversion via e.g. SVSUP_OnePlaneToBitPlane8. The following code is quite senseless, because it is much easier to use SVL_DisplayGfxBuffer() instead, but it demonstrates quite good, how this function may be used (and _this_ example definitely works ...) : ULONG GfxBufferShow(char *filename) { ULONG retval = SVERR_NO_ERROR; APTR handle = N; struct SVSUP_DisplayHandle *displayhandle = N; displayhandle = AllocVec(sizeof(struct SVSUP_DisplayHandle), MEMF_CLEAR|MEMF_PUBLIC); if(displayhandle) { SVL_GetGlobalDriver(&displayhandle->SVDriverNode, N); handle = SVL_AllocHandle(N); if(handle) { if(!(retval = SVL_InitHandleAsDOS(handle, N))) { displayhandle->WinIDCMP = IDCMP_MOUSEBUTTONS; displayhandle->ScrType = CUSTOMSCREEN; retval = SVL_ReadToGfxBuffer(handle, filename); if(!retval) retval = SVL_GetGfxBuffer( handle, &displayhandle->SVGfxBuffer, N); if(!retval && displayhandle->SVGfxBuffer) { retval = SVSUP_DisplayGfxBuffer(displayhandle); if(!retval) { if(displayhandle->Window) { WaitPort(displayhandle->Window->UserPort); } } SVSUP_UnDisplayGfxBuffer(displayhandle); } } SVL_FreeHandle(handle); }else retval = SVERR_NO_HANDLE; FreeVec(displayhandle); }else retval = SVERR_NO_MEMORY; return(retval); } The Handle has to be allocated and initialized before passing it to this function. After usage - and after calling SVSUP_UnDisplay- GfxBuffer() - it has still to be delocated. You do not need (or must) initialize all fields of the Handle structure, but set them to NULL, if you do not (or must not). It is suggested, that you'll use AllocMem/AllocVec() with the MEMF_CLEAR flag. Initialize at least the following fields : - Version (currently 4) - SVGfxBuffer (the GfxBuffer) - SVDriverNode (as returned by SVL_GetGlobalDriver) Optionally initialize the following fields : - WinIDCMP - WinFlags - ScrType After calling SVSUP_DisplayGfxBuffer(), but before SVSUP_UnDisplayGfxBuffer() you may use the following fields for read-only purposes :: - Window; - Screen; All values are used and have to be interpreted just like the corresponding parameters of the similar SVL_/SVO_ or SVD_ function calls : If you do not supply values for ScreenType, WindowIDCMP and WindowFlags, default-values will be used instead. INPUT(S) displayhandle - a handle, as defined in "superviewsupport.h". Has to be allocated and initalized by the User !! RESULT NULL or a SVERR-Errorcode. BUGS - SINCE ... version 4 of the superviewsupport.library. SEE ALSO SVSUP_UnDisplayGfxBuffer ----------------------------------------------------------------------------- NAME SVSUP_UnDisplayGfxBuffer SYNOPSIS ULONG SVSUP_UnDisplayGfxBuffer(struct SVSUP_DisplayHandle *disphandle) D0 -$a2 A1 FUNCTION This function closes a display, which has been opened via SVSUP_DisplayGfxBuffer() before. All temporary buffers etc. will be delocated, then. The supplied GfxBuffer and the Handle itself will be left intact. This call requires a valid displayhandle (which has been passed to SVSUP_DisplayGfxBuffer before). See SourceCode-example under SVSUP_DisplayGfxBuffer(). INPUT(S) displayhandle - a handle, as defined in "superviewsupport.h". Has still to be delocated by the User !! RESULT - BUGS - SINCE ... version 4 of the superviewsupport.library. SEE ALSO SVSUP_DisplayGfxBuffer ----------------------------------------------------------------------------- NAME SVSUP_FreeGfxBuffer SYNOPSIS ULONG SVSUP_FreeGfxBuffer(struct SV_GfxBuffer *gfxbuffer) D0 -$a8 A1 FUNCTION Use this function to free GfxBuffers, which are not related to any SVObject-Handles. E.g. any of the SVSUP_ScreenToXXXPlane() and SVSUP_XXXPlaneToXXXPlane() functions produce GfxBuffer, which have to be given free either via separate FreeVec() calls for the ImageData-Buffer and for the GfxBuffer itself or just by calling this function and then forgetting about it. Do not try to free buffers, which will already be freed via the next SVL_FreeHandle call. These are Buffers, which are returned by SVL_GetGfxBuffer(). INPUT(S) gfxbuffer - a valid pointer to a "stand-alone" GfxBuffer RESULT - BUGS - SINCE ... version 4 of the superviewsupport.library. SEE ALSO SVSUP_ScreenToXXXPlane(), SVSUP_XXXPlaneToXXXPlane() (XXX = (Bit | One) ----------------------------------------------------------------------------- Functions available since Version 5 : ----------------------------------------------------------------------------- NAME SVSUP_FindControlPadNoCase SYNOPSIS ULONG SVSUP_FindControlPadNoCase(struct SV_ControlPad *pad, D0 -$ae A1 UBYTE *name, A2 UBYTE **content) A3 FUNCTION like SVSUP_FindControlPad(), not not case-sensitive. INPUT(S) like SVSUP_FindControlPad() RESULT like SVSUP_FindControlPad() SINCE ... version 5 of the superviewsupport.library. SEE ALSO SVSUP_FindControlPad ----------------------------------------------------------------------------- NAME SVSUP_ModifyControlPad SYNOPSIS ULONG SVSUP_ModifyControlPad(struct SV_ControlPad *pad, D0 -$b4 A1 UBYTE *name, A2 UBYTE *content, A3 ULONG bool) D1 FUNCTION Modifies an existing ControlPad entry, if exists. Returns error, if it does not exist. May be switched between case-sensitive and case-insensitive mode. INPUT(S) pad - a pointer to a ControlPad-Structure (List-Head) name - the name of the entry to search for content - string pointer to new content or NULL bool - case-sensitive ? RESULT Boolean value. SINCE ... version 5 of the superviewsupport.library. SEE ALSO SVSUP_AddControlPad ----------------------------------------------------------------------------- NAME SVSUP_AddControlPad SYNOPSIS ULONG SVSUP_AddControlPad(struct SV_ControlPad *pad, D0 -$ba A1 UBYTE *name, A2 UBYTE *content, A3 ULONG bool) D1 FUNCTION Adds a new ControlPad entry or modifies one, if already exists. May return an error (no memory, etc.) May be switched between case-sensitive and case-insensitive mode. INPUT(S) pad - a pointer to a ControlPad-Structure (List-Head) name - the name of the entry to search for content - string pointer to content or NULL bool - case-sensitive ? RESULT Boolean value. SINCE ... version 5 of the superviewsupport.library. SEE ALSO SVSUP_ModifyControlPad ----------------------------------------------------------------------------- Functions available since Version 6 : ----------------------------------------------------------------------------- NAME SVSUP_AllocMemEntry SYNOPSIS ULONG SVSUP_AllocVMemEntry(APTR mlist, size, type) D0 -$c0 A1 D0 D1 FUNCTION Allocates memory just like SVSUP_AllocVMemEntry(), but initializes it as virtual memory. The result is a valid "VMemHandle" (numeric value for accessing the virtual memory) or NULL. The memory will _not_ be allocated right now, but a corresponding file (with this size) will be created at the location "VMEM:". You may load it into "real" memory and get a pointer to it via SVSUP_AccessVMemEntry(), but you need not do this for simply reading/writing to it (see below). After calling SVSUP_ReleaseVMemEntry() the pointer returned by SVSUP_AccessVMenEntry() would become invalid again and the memory content will be written back to "VMEM:vmem_*******". When calling SVSUP_AccessVMemEntry() again, it will be re-read from disk and re-allocated, then. Nevertheless the memory content may also be accessed without loading it to memory, via SVSUP_ReadVMemBytes() and SVSUP_WriteVMemBytes(). Take these functions for really "virtual" read and write calls. IMPORTANT NOTE: --------------- You should not specify "MEMF_CLEAR" with this function, if you don't really need this. Since AmigaDOS does not really support a function to create an EMPTY file with a specific size (SetFileSize() is not supported by all Handlers and might possibly create files, which are not really empty), the resulting virtual "on-disk buffer" then has to be cleared via separate write calls: currently we use a buffer of 255 Bytes size, so the number of calls to Write() will be something like <size>/255 (+= 1, if there's <size>%255 > 0). >>> An alternative would be to not use MEMF_CLEAR, but clear the buffer after accessing it, or - if you'll use it fully virtual - via calling SVSUP_WriteVMemBytes() with empty buffers. This will increase speed significantly. INPUT(S) mlist - a memory list pointer as from SVSUP_GetMemList() size - needed size for the memory chunk type - "MEMF_"-specification of the memory type RESULT a virtual memory handle or NULL BUGS - SINCE ... version 6 of the superviewsupport.library. SEE ALSO SVSUP_XXXXXVMemXXXXXX, SVSUP_FreeMemList ----------------------------------------------------------------------------- NAME SVSUP_AccessVMemEntry SYNOPSIS APTR SVSUP_AccessVMemEntry(APTR mlist, ULONG vmemhandle) D0 -$c6 A1 D0 FUNCTION Returns a pointer to a virtual memory chunk by loading it into memory (if not already). Identification is managed via a "virtual memory handle". INPUT(S) mlist - a memory list pointer as from SVSUP_GetMemList() handle - a valid virtual memory handle RESULT a pointer to a memory chunk of a fixed size BUGS - SINCE ... version 6 of the superviewsupport.library. SEE ALSO SVSUP_XXXXXVMemXXXXXX, SVSUP_FreeMemList ----------------------------------------------------------------------------- NAME SVSUP_ReleaseVMemEntry SYNOPSIS ULONG SVSUP_ReleaseVMemEntry(APTR mlist, ULONG vmemhandle) D0 -$cc A1 D0 FUNCTION Frees a virtual memory chunk by delocating the internal pointer to it after writing its content to a temporary file at "VMEM:". Its content may be re-loaded into memory via SVSUP_AccessVMemEntry() or simply accessed via SVSUP_ReadVMemBytes() or SVSUP_WriteVMemBytes. INPUT(S) mlist - a memory list pointer as from SVSUP_GetMemList() handle - a valid virtual memory handle RESULT a boolean (error) value BUGS - SINCE ... version 6 of the superviewsupport.library. SEE ALSO SVSUP_XXXXXVMemXXXXXX, SVSUP_FreeMemList ----------------------------------------------------------------------------- NAME SVSUP_ReadVMemBytes SYNOPSIS ULONG SVSUP_ReadVMemBytes(APTR mlist, ULONG vmemhandle, D0 -$d2 A1 D0 UBYTE *buffer, ULONG offset, ULONG size) A2 D1 D2 FUNCTION Reads a specific amount of Bytes from a specific offset of a virtual memory chunk, WITHOUT loading it into "real" memory (from-disk operation at "VMEM:"). INPUT(S) mlist - a memory list pointer as from SVSUP_GetMemList() handle - a valid virtual memory handle buffer - a buffer to read into offset - read from this offset size - read <size> bytes from there RESULT a boolean (error) value BUGS - SINCE ... version 6 of the superviewsupport.library. SEE ALSO SVSUP_XXXXXVMemXXXXXX, SVSUP_FreeMemList ----------------------------------------------------------------------------- NAME SVSUP_WriteVMemBytes SYNOPSIS ULONG SVSUP_WriteVMemBytes(APTR mlist, ULONG vmemhandle, D0 -$d8 A1 D0 UBYTE *buffer, ULONG offset, ULONG size) A2 D1 D2 FUNCTION Write a specific amount of Bytes to a specific offset in a virtual memory chunk, WITHOUT loading it into "real" memory (to-disk operation at "VMEM:"). INPUT(S) mlist - a memory list pointer as from SVSUP_GetMemList() handle - a valid virtual memory handle buffer - a buffer to write from offset - write to this offset size - write <size> bytes to there RESULT a boolean (error) value BUGS - SINCE ... version 6 of the superviewsupport.library. SEE ALSO SVSUP_XXXXXVMemXXXXXX, SVSUP_FreeMemList ----------------------------------------------------------------------------- NAME SVSUP_VecToVMemEntry SYNOPSIS ULONG SVSUP_VecToVMemEntry(APTR mlist, APTR vector, ULONG size) D0 -$de A1 A2 D0 FUNCTION This functions turns any chunk of memory (specified by "vector" and "size") into a piece of virtual memory. "vector" may alreayd be present as an entry (virtual or non-virtual) in the list (although it usually will not): this does not affect functionality, it's supported instead ! (So you'll be able to combine usage of SVSUP_Add/AllocMemEntry() and SVSUP_XXXXVMemXXX() functions !) "vector" has to be an AllocVec()ed pointer or one returned by SVSUP_AllocMemEntry(). "size" may be equal to the original size of the memory chunk, but you may also specify a smaller or bigger value. Since a bigger value might cause problems, when the CPU just looks behind the actually allocated area (and there might be nothing left ;-) the only _supported_ way is to decrease buffer size somewhat by specifying a smaller value. "size" ist just needed to determine the amount of bytes written to disk, when "virtualizing" the memory and thus also will define the size of the buffer, when re-loaded into "real" memory. Note, that the given "vector" will ALWAYS become INVALID and will be freed during the function's runtime (even if it fails, usually). INPUT(S) mlist - a memory list pointer as from SVSUP_GetMemList() vector - an AllocVec()ed pointer (or one already in the list) size - the (new) size of the virtual memory chunk RESULT a virtual memory handle or NULL BUGS - SINCE ... version 6 of the superviewsupport.library. SEE ALSO SVSUP_XXXXXVMemXXXXXX, SVSUP_FreeMemList ----------------------------------------------------------------------------- NAME SVSUP_GetVMemSize SYNOPSIS ULONG SVSUP_GetVMemSize(ULONG handle) D0 -$e4 A1 FUNCTION The size of a virtual memory chunk may be changed several times during usage, as described under SVSUP_VecToMemEntry(). If you don't want to remember it always or don't like to pass too much parameters between you private virtual memory handling functions, you may use this functions to determine the size of a specific virtual memory chunk at a specific time. It does not matter, whether the memory is currently "virtualized" or in memory, with a vector pointing at it. INPUT(S) handle - a valid virtual memory handle (any state) RESULT the size of the virtual memory or NULL BUGS - SINCE ... version 6 of the superviewsupport.library. SEE ALSO SVSUP_XXXXXVMemXXXXXX, SVSUP_FreeMemList -----------------------------------------------------------------------------