home *** CD-ROM | disk | FTP | other *** search
/ Amiga ISO Collection / AmigaUtilCD1.iso / GFX / viewer / SuperView-Lib.LHA / superview-lib / Programmers / Docs / SVObject_Ref_ENG.doc < prev    next >
Encoding:
Text File  |  1994-09-10  |  18.5 KB  |  833 lines
  1.  
  2.    $VER: SVObject_Ref_ENG.doc V2.3 (16.8.94)
  3.  
  4.    © 1994 by Andreas R. Kleinert. All rights reserved.
  5.  
  6.    - Feel free to translate this Doc-File into other languages. -
  7.  
  8.        Andreas R. Kleinert,
  9.        Grube Hohe Grethe 23,
  10.        D-57074 Siegen,
  11.        Germany.                        email : Fido 2:2457/345.10
  12.                                                (checked weekly)
  13.  
  14.    * DO _NEVER_ ACCESS ANY SVOBJECTS DIRECTLY.
  15.    * DO NEVER BYPASS superview.library !
  16.  
  17.    THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SVOBJECTS :
  18.  
  19.    Here is a listing of the function set, which any of the version 1
  20.    and version 2 SVObjects does contain, in an Autodoc-like style of
  21.    description :
  22.  
  23.         SVO_AllocHandle            ; since Version 1
  24.         SVO_FreeHandle
  25.         SVO_Show
  26.         SVO_Write
  27.         SVO_CloseDisplay
  28.         SVO_FreeResources
  29.         SVO_SetAccessMode
  30.         SVL_SetScreenType
  31.         SVO_SetWindowFlags
  32.         SVO_SetWindowIDCMP
  33.         SVO_GetScreenAddress
  34.         SVO_GetWindowAddress
  35.         SVO_SetScreenAddress
  36.         SVO_SetWindowAddress
  37.         SVO_SetWriteName
  38.         SVO_SetReadName
  39.         SVO_FileInfoRequest
  40.         SVO_CheckFileType
  41.         SVO_ReadToGfxBuffer        ; since Version 2
  42.         SVO_GetGfxBuffer
  43.         SVO_SetGfxBuffer
  44.  
  45.  (you will never find any notes belonging to "BUGS", because any SVObject
  46.   may have its own ...)
  47.  
  48. -----------------------------------------------------------------------------
  49.    Functions available since Version 1 :
  50. -----------------------------------------------------------------------------
  51.  
  52.    NAME
  53.         SVO_AllocHandle
  54.  
  55.    SYNOPSIS
  56.  
  57.         APTR SVO_AllocHandle(APTR future)
  58.         D0   -$1e            A1
  59.  
  60.    FUNCTION
  61.  
  62.         Allocates a handle for accessing a Graphic via this SVObject.
  63.  
  64.    INPUT(S)
  65.  
  66.         future - always NULL yet
  67.  
  68.    RESULT
  69.  
  70.         A pointer to a new allocated Handle or NULL, if allocation failed.
  71.  
  72.    WARNING
  73.  
  74.         Test, if the result was NULL, or not !
  75.  
  76.    SINCE
  77.  
  78.         ... Version 1 SVObjects.
  79.  
  80.    SEE ALSO
  81.  
  82.         SVO_FreeResources, SVO_FreeHandle
  83.  
  84. -----------------------------------------------------------------------------
  85.  
  86.    NAME
  87.         SVO_FreeHandle
  88.  
  89.    SYNOPSIS
  90.  
  91.         VOID SVO_FreeHandle(APTR handle)
  92.         D0   -$24           A1
  93.  
  94.    FUNCTION
  95.  
  96.        Aborts showing, frees all Resources and delocates a Handle, which has
  97.        been allocated with SVO_AllocHandle before.
  98.  
  99.  
  100.        For programmers of SVObjects :
  101.  
  102.        Note, that this function should call
  103.  
  104.           SVO_CloseDisplay(SVHandle);
  105.           SVO_FreeResources(SVHandle);
  106.  
  107.        internally always. Otherwise memory might be lost, because
  108.        superview.library might only make a call to SVO_FreeHandle(),
  109.        without closing the display/freeing the resources before.
  110.  
  111.    INPUT(S)
  112.  
  113.         handle - a valid handle
  114.  
  115.    RESULT
  116.  
  117.         -
  118.  
  119.    SINCE
  120.  
  121.         ... Version 1 SVObjects.
  122.  
  123.    SEE ALSO
  124.  
  125.         SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeResources
  126.  
  127. -----------------------------------------------------------------------------
  128.  
  129.    NAME
  130.         SVO_Show
  131.  
  132.    SYNOPSIS
  133.  
  134.         ULONG SVO_Show(APTR handle)
  135.         D0    -$2a     A1
  136.  
  137.    FUNCTION
  138.  
  139.         Loads and shows the Graphic described by a previously set FileName
  140.         or just shows the Graphic, if already been loaded.
  141.  
  142.         Showing can be aborted either via full delocation of the handle
  143.         or via Closing the Display with SVO_CloseDisplay.
  144.  
  145.    INPUT(S)
  146.  
  147.         handle   - a valid handle
  148.  
  149.    RESULT
  150.  
  151.         NULL or an adequate SVERR-Errorcode.
  152.  
  153.    SINCE
  154.  
  155.         ... Version 1 SVObjects.
  156.  
  157.    SEE ALSO
  158.  
  159.         SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeHandle
  160.  
  161. -----------------------------------------------------------------------------
  162.  
  163.    NAME
  164.         SVO_Write
  165.  
  166.    SYNOPSIS
  167.  
  168.         ULONG SVO_Write(APTR handle)
  169.         D0    -$30      A1
  170.  
  171.    FUNCTION
  172.  
  173.         Writes the currently loaded (as GfxBuffer) or displayed (on Screen)
  174.         graphic into a file (or onto any other medium, e.g. ClipBoard),
  175.         which has been specified via the appropriate function calls
  176.         before (SVO_SetAccessMode())
  177.  
  178.    INPUT(S)
  179.  
  180.         handle        - a valid handle
  181.  
  182.    RESULT
  183.  
  184.         NULL or an adequate SVERR-Errorcode.
  185.  
  186.    SINCE
  187.  
  188.         ... Version 1 SVObjects.
  189.  
  190.    SEE ALSO
  191.  
  192.  
  193.         SVO_AllocHandle, SVO_FreeHandle
  194.  
  195. -----------------------------------------------------------------------------
  196.  
  197.    NAME
  198.         SVO_CloseDisplay
  199.  
  200.    SYNOPSIS
  201.  
  202.         VOID SVO_CloseDisplay(APTR handle)
  203.         D0   -$36             A1
  204.  
  205.    FUNCTION
  206.  
  207.         Aborts showing the Graphic, indentified by the handle.
  208.         The Display-Screen is closed, but no other resources are given free.
  209.  
  210.    INPUT(S)
  211.  
  212.         handle - a valid handle
  213.  
  214.    RESULT
  215.  
  216.         -
  217.  
  218.    SINCE
  219.  
  220.         ... Version 1 SVObjects.
  221.  
  222.    SEE ALSO
  223.  
  224.         SVO_FreeResources, SVO_FreeHandle
  225.  
  226. -----------------------------------------------------------------------------
  227.  
  228.    NAME
  229.         SVO_FreeResources
  230.  
  231.    SYNOPSIS
  232.  
  233.         VOID SVO_FreeResources(APTR handle)
  234.         D0   -$3c              A1
  235.  
  236.    FUNCTION
  237.  
  238.         Frees all resources belonging to the specific Graphic,
  239.         indentified by the handle, which are not needed to just show it.
  240.         The display as such will not be closed.
  241.  
  242.         Note, that SVO_FileInfoRequest() will no longer work, then
  243.         ("No file loaded" or similar request appears).
  244.  
  245.    INPUT(S)
  246.  
  247.         handle - a valid handle
  248.  
  249.    RESULT
  250.  
  251.         -
  252.  
  253.    SINCE
  254.  
  255.         ... Version 1 SVObjects.
  256.  
  257.    SEE ALSO
  258.  
  259.         SVO_AllocHandle, SVO_CloseDisplay, SVO_FreeHandle
  260.  
  261. -----------------------------------------------------------------------------
  262.  
  263.    NAME
  264.         SVO_SetAccessMode
  265.  
  266.    SYNOPSIS
  267.  
  268.         ULONG SVO_SetAccessMode(APTR handle, ULONG mode)
  269.         D0    -$42              A1           D1
  270.  
  271.    FUNCTION
  272.  
  273.         Initializes a Handle e.g. for AmigaDOS access, so that the
  274.         separately specified AmigaDOS FileName will be used.
  275.         Another possibility is sometimes to initialize Handles
  276.         for ClipBoard Access (depending on the specific SVObject,
  277.         e.g. IFF-ILBM).
  278.  
  279.    INPUT(S)
  280.  
  281.         handle - a valid handle
  282.         mode   - one of the supported "medium" Flags
  283.  
  284.    RESULT
  285.  
  286.         NULL or an adequate SVERR-Errorcode.
  287.  
  288.    SINCE
  289.  
  290.         ... Version 1 SVObjects.
  291.  
  292.    SEE ALSO
  293.  
  294.         SVO_SetWriteName
  295.  
  296. -----------------------------------------------------------------------------
  297.  
  298.    NAME
  299.         SVL_SetScreenType
  300.  
  301.    SYNOPSIS
  302.  
  303.         ULONG SVL_SetScreenType(APTR handle, ULONG type, APTR future)
  304.         D0    -$48              A1              D1          A2
  305.  
  306.    FUNCTION
  307.  
  308.         Specifies, which ScreenType the Screen should have, on which the
  309.         graphic is to be displayed later.
  310.  
  311.         This statement may have no effect, if the SVObject uses external
  312.         drivers for displaying (e.g. EGS.svdriver will ignore this
  313.         setting more or less).
  314.  
  315.    INPUT(S)
  316.  
  317.         handle - a valid handle
  318.         type   - a ScreenType descriptor, like e.g. CUSTOMSCREEN
  319.         future - always NULL yet
  320.  
  321.    RESULT
  322.  
  323.         NULL or an adequate SVERR-Errorcode.
  324.  
  325.    SINCE
  326.  
  327.         ... Version 1 SVObjects.
  328.  
  329.    SEE ALSO
  330.  
  331.         SVO_GetScreenAddress
  332.  
  333. -----------------------------------------------------------------------------
  334.  
  335.    NAME
  336.         SVO_SetWindowFlags
  337.  
  338.    SYNOPSIS
  339.  
  340.         ULONG SVO_SetWindowFlags(APTR handle, ULONG flags, APTR future)
  341.         D0    -$4e               A1           D1           A2
  342.  
  343.    FUNCTION
  344.  
  345.         Specifies, which Flags the Window should have, on which the
  346.         graphic is to be displayed later.
  347.  
  348.         This statement may have no effect, if the SVObject uses external
  349.         drivers for displaying (e.g. EGS.svdriver will ignore this
  350.         setting more or less).
  351.  
  352.    INPUT(S)
  353.  
  354.         handle     - a valid handle
  355.         flags      - valid WindowFlags, like e.g. WFLG_BACKDROP
  356.         future     - always NULL yet
  357.  
  358.    RESULT
  359.  
  360.         NULL or an adequate SVERR-Errorcode.
  361.  
  362.    SINCE
  363.  
  364.         ... Version 1 SVObjects.
  365.  
  366.    SEE ALSO
  367.  
  368.         SVO_Write
  369.  
  370. -----------------------------------------------------------------------------
  371.  
  372.    NAME
  373.         SVO_SetWindowIDCMP
  374.  
  375.    SYNOPSIS
  376.  
  377.         ULONG SVO_SetWindowIDCMP(APTR handle, ULONG idcmp, APTR future)
  378.         D0    -$54               A1           D1           A2
  379.  
  380.    FUNCTION
  381.  
  382.         Specifies, which IDCMP the Window should have, on which the
  383.         graphic is to be displayed later.
  384.  
  385.         This statement may have no effect, if the SVObject uses external
  386.         drivers for displaying (e.g. EGS.svdriver will ignore this
  387.         setting more or less).
  388.  
  389.    INPUT(S)
  390.  
  391.         handle - a valid handle
  392.         idcmp  - a valid set of IDCMP-Flags
  393.         future - always NULL yet
  394.  
  395.    RESULT
  396.  
  397.         NULL or an adequate SVERR-Errorcode.
  398.  
  399.    SINCE
  400.  
  401.         ... Version 1 SVObjects.
  402.  
  403.    SEE ALSO
  404.  
  405.         SVO_Show
  406.  
  407. -----------------------------------------------------------------------------
  408.  
  409.    NAME
  410.         SVO_GetScreenAddress
  411.  
  412.    SYNOPSIS
  413.  
  414.         struct Screen *SVO_GetScreenAddress(APTR handle, future)
  415.         D0             -$5a                 A1           A2
  416.  
  417.    FUNCTION
  418.  
  419.         While displaying, the address of the DisplayScreen is returned
  420.         by this function.
  421.         See example SourceCodes for more and detailed information.
  422.  
  423.    INPUT(S)
  424.  
  425.         handle - a valid handle
  426.         future - always NULL yet
  427.  
  428.    RESULT
  429.  
  430.         A valid ScreenPointer or NULL.
  431.  
  432.    SINCE
  433.  
  434.         ... Version 1 SVObjects.
  435.  
  436.    SEE ALSO
  437.  
  438.         SVO_GetWindowAddress
  439.  
  440. -----------------------------------------------------------------------------
  441.  
  442.    NAME
  443.         SVO_GetWindowAddress
  444.  
  445.    SYNOPSIS
  446.  
  447.         struct Window *SVO_GetWindowAddress(APTR handle, future)
  448.         D0             -$60                 A1           A2
  449.  
  450.    FUNCTION
  451.  
  452.         While displaying, the address of the DisplayWindows is returned
  453.         by this function.
  454.         See example SourceCodes for more and detailed information.
  455.  
  456.    INPUT(S)
  457.  
  458.         handle - a valid handle
  459.         future - always NULL yet
  460.  
  461.    RESULT
  462.  
  463.         A valid WindowPointer or NULL.
  464.  
  465.    SINCE
  466.  
  467.         ... Version 1 SVObjects.
  468.  
  469.    SEE ALSO
  470.  
  471.         SVO_GetScreenAddress
  472.  
  473. -----------------------------------------------------------------------------
  474.  
  475.    NAME
  476.         SVO_SetScreenAddress
  477.  
  478.    SYNOPSIS
  479.  
  480.         ULONG SVO_SetScreenAddress(APTR handle, struct Screen *sc, APTR future)
  481.         D0    -$66                 A1           A2                 A3
  482.  
  483.    FUNCTION
  484.  
  485.         Sets the address of a Screen, which should be used as the Source
  486.         for the next write action (instead of GfxBuffer).
  487.  
  488.         See description there and example SourceCodes for more and
  489.         detailed information.
  490.  
  491.    INPUT(S)
  492.  
  493.         handle - a valid handle
  494.         sc     - a valid ScreenPointer
  495.         future - always NULL yet
  496.  
  497.    RESULT
  498.  
  499.         NULL or an adequate SVERR-Errorcode.
  500.  
  501.    SINCE
  502.  
  503.         ... Version 1 SVObjects.
  504.  
  505.    SEE ALSO
  506.  
  507.         SVO_SetWindowAddress
  508.  
  509. -----------------------------------------------------------------------------
  510.  
  511.  
  512.    NAME
  513.         SVO_SetWindowAddress
  514.  
  515.    SYNOPSIS
  516.  
  517.         ULONG SVO_SetWindowAddress(APTR handle, struct Window *wi, APTR future)
  518.         D0    -$6c                 A1           A2                 A3
  519.  
  520.    FUNCTION
  521.  
  522.         Sets the address of a Window, which should be used as the Source
  523.         for the next write action (instead of GfxBuffer).
  524.         Also set the corresponding Screen address !
  525.  
  526.         See description there and example SourceCodes for more and
  527.         detailed information.
  528.  
  529.    INPUT(S)
  530.  
  531.         handle - a valid handle
  532.         wi     - a valid WindowPointer
  533.         future - always NULL yet
  534.  
  535.    RESULT
  536.  
  537.         NULL or an adequate SVERR-Errorcode.
  538.  
  539.    SINCE
  540.  
  541.         ... Version 1 SVObjects.
  542.  
  543.    SEE ALSO
  544.  
  545.         SVO_SetScreenAddress
  546.  
  547. -----------------------------------------------------------------------------
  548.  
  549.    NAME
  550.         SVO_SetWriteName
  551.  
  552.    SYNOPSIS
  553.  
  554.         ULONG SVO_SetWriteName(APTR handle, UBYTE *name, APTR future)
  555.         D0    -$72             A1           A2           A3
  556.  
  557.    FUNCTION
  558.  
  559.         Sets a filename for the next write action.
  560.  
  561.    INPUT(S)
  562.  
  563.         handle - a valid handle
  564.         name   - a valid AmigaDOS FileName
  565.         future - always NULL yet
  566.  
  567.    RESULT
  568.  
  569.         NULL or an adequate SVERR-Errorcode.
  570.  
  571.    SINCE
  572.  
  573.         ... Version 1 SVObjects.
  574.  
  575.    SEE ALSO
  576.  
  577.         SVO_SetReadName
  578.  
  579. -----------------------------------------------------------------------------
  580.  
  581.    NAME
  582.         SVO_SetReadName
  583.  
  584.    SYNOPSIS
  585.  
  586.         ULONG SVO_SetReadName(APTR handle, UBYTE *name, APTR future)
  587.         D0    -$78            A1           A2           A3
  588.  
  589.    FUNCTION
  590.  
  591.         Sets a filename for the next read action.
  592.  
  593.    INPUT(S)
  594.  
  595.         handle - a valid handle
  596.         name   - a valid AmigaDOS FileName
  597.         future - always NULL yet
  598.  
  599.    RESULT
  600.  
  601.         NULL or an adequate SVERR-Errorcode.
  602.  
  603.    SINCE
  604.  
  605.         ... Version 1 SVObjects.
  606.  
  607.    SEE ALSO
  608.  
  609.         SVO_SetWriteName
  610.  
  611. -----------------------------------------------------------------------------
  612.  
  613.    NAME
  614.         SVO_FileInfoRequest
  615.  
  616.    SYNOPSIS
  617.  
  618.         ULONG SVO_FileInfoRequest(APTR handle, struct Window *window,
  619.         D0    -$7e                A1           A2
  620.  
  621.                                   APTR future)
  622.                                   A3
  623.  
  624.    FUNCTION
  625.  
  626.         Pops up an Info-Requester with more or less detailed information
  627.         on the currently loaded Graphic.
  628.         A window pointer may be given to select the place to pop it up.
  629.  
  630.         Note, that this function will fail, if you already called
  631.         SVO_FreeResources() (might result in a "No file loaded" message) !
  632.  
  633.    INPUT(S)
  634.  
  635.         handle - a valid handle
  636.         window - a valid Window Pointer or NULL
  637.         future - always NULL yet
  638.  
  639.    RESULT
  640.  
  641.         NULL or an adequate SVERR-Errorcode.
  642.  
  643.    SINCE
  644.  
  645.         ... Version 1 SVObjects.
  646.  
  647.    SEE ALSO
  648.  
  649.         -
  650.  
  651. -----------------------------------------------------------------------------
  652.  
  653.    NAME
  654.         SVO_CheckFileType
  655.  
  656.    SYNOPSIS
  657.  
  658.         ULONG SVO_CheckFileType(BPTR filehandle, UBYTE *filename,
  659.         D0    -$84              A1                 A2
  660.  
  661.                                 struct SVOCheckFile *svo_check)
  662.                                 A3
  663.  
  664.    FUNCTION
  665.  
  666.         Checks, if the given file (or ClipBoard entry, or whatever)
  667.         fits to this SVObject and can be handled therein.
  668.  
  669.         Upto Version 4 of superview.library ClipBoard-Support with
  670.         external SVObjects would not have worked anymore.
  671.  
  672.         Since V4 the specification of external Version 2 SVObjects
  673.         has been modified to allow ClipBoard and other media usage :
  674.         To preserve compatibility, this has been done by using the
  675.         "future" parameter as a pointer to a SVO_CheckFile-structure
  676.         (defined in "include:svobjects/svobjects.h"), which contains
  677.         additional media information (sometimes !).
  678.  
  679.         This pointer may be NULL, so that you have to assume default
  680.         settings, if there's not such a structure.
  681.         For disk-access, this pointer will not be set at all, anyway.
  682.  
  683.         Also be prepared, to handle NULL pointers to filename :
  684.         if ClipBoard usage is forced, there will no filename be needed.
  685.         If you don't support any filename-less medias, just do a silent
  686.         exit.
  687.         Currently - for compatibility reasons - superview.library will
  688.         supply a dummy filename and a dummy file for those SVObjects,
  689.         which may not handle a NULL pointer correctly.
  690.  
  691.         So handle SVOCheckFile structures with a HIGHER priority, because
  692.         currently there's always a dummy-file (mostly empty) available.
  693.  
  694.    INPUT(S)
  695.  
  696.         handle    - a valid handle
  697.         name      - a valid AmigaDOS FileName
  698.         svo_check - a pointer to a SVOCheckFile structure or NULL
  699.                     for disk-access (default)
  700.  
  701.    RESULT
  702.  
  703.         NULL or an adequate SVERR-Errorcode.
  704.  
  705.    SINCE
  706.  
  707.         ... Version 1 SVObjects.
  708.  
  709.    SEE ALSO
  710.  
  711.         -
  712.  
  713. -----------------------------------------------------------------------------
  714.    Functions added with Version 2 :
  715. -----------------------------------------------------------------------------
  716.  
  717.    NAME
  718.         SVO_ReadToGfxBuffer
  719.  
  720.    SYNOPSIS
  721.  
  722.         ULONG SVO_ReadToGfxBuffer(APTR handle)
  723.         D0    -$8a                A1
  724.  
  725.    FUNCTION
  726.  
  727.         Does a read action to a GfxBuffer, using the current settings
  728.         for FileName and medium.
  729.  
  730.         This Buffer may be displayed via SVO_Show and/or exported
  731.         via SVO_GetGfxBuffer.
  732.  
  733.    INPUT(S)
  734.  
  735.         handle    - a valid handle
  736.  
  737.    RESULT
  738.  
  739.         NULL or an adequate SVERR-Errorcode.
  740.  
  741.    SINCE
  742.  
  743.         ... Version 2 SVObjects.
  744.  
  745.    SEE ALSO
  746.  
  747.         SVO_Show, SVO_GetGfxBuffer
  748.  
  749. -----------------------------------------------------------------------------
  750.  
  751.    NAME
  752.         SVO_GetGfxBuffer
  753.  
  754.    SYNOPSIS
  755.  
  756.         ULONG SVO_GetGfxBuffer(APTR handle, struct SV_GfxBuffer **buffer,
  757.         D0    -$90                A1        A2
  758.  
  759.                                ULONG future)
  760.                                A3
  761.  
  762.    FUNCTION
  763.  
  764.         Initializes a given pointer with the address to the GfxBuffer for
  765.         the currently loaded Graphic.
  766.  
  767.         This Buffer MUST NOT be given free by-hand (use SVO_FreeHandle
  768.         or SVO_FreeResources on the main handle) and may still be
  769.         displayed via SVO_Show or saved anywhere else.
  770.  
  771.    INPUT(S)
  772.  
  773.         handle    - a valid handle
  774.         buffer    - a pointer to a SV_GfxBuffer pointer, which should be
  775.                     initialized with a valid pointer
  776.         future    - always NULL yet
  777.  
  778.    RESULT
  779.  
  780.         NULL or an adequate SVERR-Errorcode.
  781.  
  782.    SINCE
  783.  
  784.         ... Version 2 SVObjects.
  785.  
  786.    SEE ALSO
  787.  
  788.         SVO_ReadToGfxBuffer, SVO_Show, SVO_SetGfxBuffer, SVO_Write
  789.  
  790. -----------------------------------------------------------------------------
  791.  
  792.    NAME
  793.         SVO_SetGfxBuffer
  794.  
  795.    SYNOPSIS
  796.  
  797.         ULONG SVO_SetGfxBuffer(APTR handle, struct SV_GfxBuffer *buffer,
  798.         D0    -$90                A1        A2
  799.  
  800.                                ULONG future)
  801.                                A3
  802.  
  803.    FUNCTION
  804.  
  805.         Initializes the given handle with a pointer to a SV_GfxBuffer, which
  806.         should be used for the next write action.
  807.  
  808.         This Buffer STILL HAS TO BE GIVEN FREE the way it has been allocated
  809.         (usually via a SVO_FreeHandle or SVO_FreeResources call with the
  810.         origin handle) and may still be displayed via SVO_Show or saved
  811.         anywhere else.
  812.  
  813.    INPUT(S)
  814.  
  815.         handle    - a valid handle
  816.         buffer    - a pointer to a SV_GfxBuffer pointer, which should be
  817.                     used to initialize the handle for a write action
  818.         future    - always NULL yet
  819.  
  820.    RESULT
  821.  
  822.         NULL or an adequate SVERR-Errorcode.
  823.  
  824.    SINCE
  825.  
  826.         ... Version 2 SVObjects.
  827.  
  828.    SEE ALSO
  829.  
  830.         SVO_ReadToGfxBuffer, SVO_Show, SVO_GetGfxBuffer, SVO_Write
  831.  
  832. -----------------------------------------------------------------------------
  833.