home *** CD-ROM | disk | FTP | other *** search
/ Fresh Fish 5 / FreshFish_July-August1994.bin / useful / dist / gfx / show / superview-lib / programmers / docs / svdriver_ref_eng.doc < prev    next >
Text File  |  1994-07-04  |  9KB  |  442 lines
  1.  
  2.    $VER: Reference_ENG.doc V1.1 (27.5.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
  12.  
  13.    * DO _NEVER_ ACCESS ANY SVDRIVERS DIRECTLY.
  14.    * DO NEVER BYPASS superview.library !
  15.  
  16.    THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SVDRIVERS :
  17.  
  18.    Here is a listing of the function set, which any of the version 1
  19.    SVDrivers does contain, in an Autodoc-like style of description :
  20.  
  21.     SVD_AllocHandle        ; since Version 1
  22.     SVD_FreeHandle
  23.     SVD_CloseDisplay
  24.     SVD_FreeResources
  25.     SVD_SetGfxBuffer
  26.     SVD_DisplayGfxBuffer
  27.     SVL_SetScreenType
  28.     SVD_SetWindowFlags
  29.     SVD_SetWindowIDCMP
  30.     SVD_GetScreenAddress
  31.     SVD_GetWindowAddress
  32.  
  33.  (you will never find any notes belonging to "BUGS", because any SVDriver
  34.   may have its own ...)
  35.  
  36. -----------------------------------------------------------------------------
  37.    Functions available since Version 1 :
  38. -----------------------------------------------------------------------------
  39.  
  40.    NAME
  41.     SVD_AllocHandle
  42.  
  43.    SYNOPSIS
  44.  
  45.     APTR SVD_AllocHandle(APTR future)
  46.     D0   -$1e         A1
  47.  
  48.    FUNCTION
  49.  
  50.     Allocates a handle for displaying a GfxBuffer via this SVDriver.
  51.  
  52.    INPUT(S)
  53.  
  54.     future - always NULL yet
  55.  
  56.    RESULT
  57.  
  58.     A pointer to a new allocated Handle or NULL, if allocation failed.
  59.  
  60.    WARNING
  61.  
  62.     Test, if the result was NULL, or not !
  63.  
  64.    SINCE
  65.  
  66.     ... Version 1 SVDrivers.
  67.  
  68.    SEE ALSO
  69.  
  70.     SVD_FreeResources, SVD_FreeHandle
  71.  
  72. -----------------------------------------------------------------------------
  73.  
  74.    NAME
  75.     SVD_FreeHandle
  76.  
  77.    SYNOPSIS
  78.  
  79.     VOID SVD_FreeHandle(APTR handle)
  80.     D0   -$24        A1
  81.  
  82.    FUNCTION
  83.  
  84.        Stops showing, frees all Resources and delocates a Handle, which has
  85.        been allocated with SVD_AllocHandle before.
  86.  
  87.  
  88.        For programmers of SVDrivers :
  89.  
  90.        Note, that this function should call
  91.  
  92.       SVD_CloseDisplay(SVHandle);
  93.       SVD_FreeResources(SVHandle);
  94.  
  95.        always. Otherwise memory might be lost.
  96.  
  97.    INPUT(S)
  98.  
  99.     handle - a valid handle
  100.  
  101.    RESULT
  102.  
  103.     -
  104.  
  105.    SINCE
  106.  
  107.     ... Version 1 SVDrivers.
  108.  
  109.    SEE ALSO
  110.  
  111.     SVD_AllocHandle, SVD_CloseDisplay, SVD_FreeResources
  112.  
  113. -----------------------------------------------------------------------------
  114.  
  115.    NAME
  116.     SVD_CloseDisplay
  117.  
  118.    SYNOPSIS
  119.  
  120.     VOID SVD_CloseDisplay(APTR handle)
  121.     D0   -$2a          A1
  122.  
  123.    FUNCTION
  124.  
  125.     Stops showing the Graphic, indentified by the handle.
  126.     The Display-Screen is closed, but no Resources are given free.
  127.  
  128.    INPUT(S)
  129.  
  130.     handle - a valid handle
  131.  
  132.    RESULT
  133.  
  134.     -
  135.  
  136.    SINCE
  137.  
  138.     ... Version 1 SVDrivers.
  139.  
  140.    SEE ALSO
  141.  
  142.     SVD_FreeResources, SVD_FreeHandle
  143.  
  144. -----------------------------------------------------------------------------
  145.  
  146.    NAME
  147.     SVD_FreeResources
  148.  
  149.    SYNOPSIS
  150.  
  151.     VOID SVD_FreeResources(APTR handle)
  152.     D0   -$30           A1
  153.  
  154.    FUNCTION
  155.  
  156.     Frees all resources belonging to the specific Graphic,
  157.     indentified by the handle, which are not needed to just show it.
  158.     The Display will not be closed.
  159.  
  160.    INPUT(S)
  161.  
  162.     handle - a valid handle
  163.  
  164.    RESULT
  165.  
  166.     -
  167.  
  168.    SINCE
  169.  
  170.     ... Version 1 SVDrivers.
  171.  
  172.    SEE ALSO
  173.  
  174.     SVD_AllocHandle, SVD_CloseDisplay, SVD_FreeHandle
  175.  
  176. -----------------------------------------------------------------------------
  177.  
  178.    NAME
  179.     SVD_SetGfxBuffer
  180.  
  181.    SYNOPSIS
  182.  
  183.     ULONG SVD_SetGfxBuffer(APTR handle, struct SV_GfxBuffer *buffer,
  184.     D0    -$36           A1        A2
  185.  
  186.                    ULONG future)
  187.                    A3
  188.  
  189.    FUNCTION
  190.  
  191.     Initializes the given handle with a pointer to a SV_GfxBuffer, which
  192.     should be used with the next call of SVD_DisplayGfxBuffer (see there).
  193.  
  194.     This Buffer STILL HAS TO BE GIVEN FREE the way it has been allocated
  195.     (see documentation of SVObjects and superviewsupport.library)
  196.     and may still be displayed via SVD_DisplayGfxBuffer or saved
  197.     anywhere else.
  198.  
  199.    INPUT(S)
  200.  
  201.     handle      - a valid handle
  202.     buffer      - a pointer to a valid SV_GfxBuffer
  203.     future      - always NULL yet
  204.  
  205.    RESULT
  206.  
  207.     NULL or an adequate SVERR-Errorcode.
  208.  
  209.    SINCE
  210.  
  211.     ... Version 1 SVDrivers.
  212.  
  213.    SEE ALSO
  214.  
  215.     SVD_DisplayGfxBuffer
  216.  
  217. -----------------------------------------------------------------------------
  218.  
  219.    NAME
  220.     SVD_DisplayGfxBuffer
  221.  
  222.    SYNOPSIS
  223.  
  224.     ULONG SVD_DisplayGfxBuffer(APTR handle, future)
  225.     D0    -$3c           A1        A2
  226.  
  227.    FUNCTION
  228.  
  229.     Displays the GfxBuffer (which has been set via SVD_SetGfxBuffer before)
  230.     in the way, which is native to this SVDriver (e.g. on an Intuition
  231.     Screen, an EGS-Screen or into NIL ...)
  232.  
  233.    INPUT(S)
  234.  
  235.     handle      - a valid handle
  236.     future      - always NULL yet
  237.  
  238.    RESULT
  239.  
  240.     NULL or an adequate SVERR-Errorcode.
  241.  
  242.    SINCE
  243.  
  244.     ... Version 1 SVDrivers.
  245.  
  246.    SEE ALSO
  247.  
  248.     SVD_SetGfxBuffer
  249.  
  250. -----------------------------------------------------------------------------
  251.  
  252.    NAME
  253.     SVL_SetScreenType
  254.  
  255.    SYNOPSIS
  256.  
  257.     ULONG SVL_SetScreenType(APTR handle, ULONG type, APTR future)
  258.     D0    -$42        A1         D1      A2
  259.  
  260.    FUNCTION
  261.  
  262.     Specifies, which ScreenType the Screen should have, on which the
  263.     graphic is to be displayed later.
  264.  
  265.     This statement may have no effect, if the SVDriver uses non-Intuition
  266.     ways of displaying or exporting the GfxBuffer (e.g. EGS.svdriver will
  267.     ignore this setting more or less).
  268.  
  269.    INPUT(S)
  270.  
  271.     handle - a valid handle
  272.     type   - a ScreenType descriptor, like e.g. CUSTOMSCREEN
  273.     future - always NULL yet
  274.  
  275.    RESULT
  276.  
  277.     NULL or an adequate SVERR-Errorcode.
  278.  
  279.    SINCE
  280.  
  281.     ... Version 1 SVDrivers.
  282.  
  283.    SEE ALSO
  284.  
  285.     SVD_GetScreenAddress
  286.  
  287. -----------------------------------------------------------------------------
  288.  
  289.    NAME
  290.     SVD_SetWindowFlags
  291.  
  292.    SYNOPSIS
  293.  
  294.     ULONG SVD_SetWindowFlags(APTR handle, ULONG flags, APTR future)
  295.     D0    -$48         A1          D1       A2
  296.  
  297.    FUNCTION
  298.  
  299.     Specifies, which Flags the Window should have, on which the
  300.     graphic is to be displayed later.
  301.  
  302.     This statement may have no effect, if the SVDriver uses non-Intuition
  303.     ways of displaying or exporting the GfxBuffer (e.g. EGS.svdriver will
  304.     ignore this setting more or less).
  305.  
  306.    INPUT(S)
  307.  
  308.     handle       - a valid handle
  309.     flags       - valid WindowFlags, like e.g. WFLG_BACKDROP
  310.     future       - always NULL yet
  311.  
  312.    RESULT
  313.  
  314.     NULL or an adequate SVERR-Errorcode.
  315.  
  316.    SINCE
  317.  
  318.     ... Version 1 SVDrivers.
  319.  
  320.    SEE ALSO
  321.  
  322.     SVD_SetWindowIDCMP, SVD_GetWindowAddress
  323.  
  324. -----------------------------------------------------------------------------
  325.  
  326.    NAME
  327.     SVD_SetWindowIDCMP
  328.  
  329.    SYNOPSIS
  330.  
  331.     ULONG SVD_SetWindowIDCMP(APTR handle, ULONG idcmp, APTR future)
  332.     D0    -$4e         A1          D1       A2
  333.  
  334.    FUNCTION
  335.  
  336.     Specifies, which IDCMP the Window should have, on which the
  337.     graphic is to be displayed later.
  338.  
  339.     This statement may have no effect, if the SVDriver uses non-Intuition
  340.     ways of displaying or exporting the GfxBuffer (e.g. EGS.svdriver will
  341.     ignore this setting more or less).
  342.  
  343.    INPUT(S)
  344.  
  345.     handle - a valid handle
  346.     idcmp  - a valid set of IDCMP-Flags
  347.     future - always NULL yet
  348.  
  349.    RESULT
  350.  
  351.     NULL or an adequate SVERR-Errorcode.
  352.  
  353.    SINCE
  354.  
  355.     ... Version 1 SVDrivers.
  356.  
  357.    SEE ALSO
  358.  
  359.     SVD_Show
  360.  
  361. -----------------------------------------------------------------------------
  362.  
  363.    NAME
  364.     SVD_GetScreenAddress
  365.  
  366.    SYNOPSIS
  367.  
  368.     struct Screen *SVD_GetScreenAddress(APTR handle, future)
  369.     D0           -$54            A1         A2
  370.  
  371.    FUNCTION
  372.  
  373.     While displaying, the Address of the DisplayScreen can be get
  374.     via this function.
  375.     See description there and example SourceCodes for more and
  376.     detailed information.
  377.  
  378.     This statement may not return a pointer to the real DisplayScreen,
  379.     if the SVDriver uses non-Intuition ways of displaying or exporting
  380.     the GfxBuffer (e.g. EGS.svdriver uses EGS-Screens, which are not
  381.     compatible with Intuition Screens).
  382.     So NULL or a pointer to a Dummy-Screen might be returned sometimes.
  383.  
  384.    INPUT(S)
  385.  
  386.     handle - a valid handle
  387.     future - always NULL yet
  388.  
  389.    RESULT
  390.  
  391.     A valid ScreenPointer or NULL.
  392.  
  393.    SINCE
  394.  
  395.     ... Version 1 SVDrivers.
  396.  
  397.    SEE ALSO
  398.  
  399.     SVD_GetWindowAddress
  400.  
  401. -----------------------------------------------------------------------------
  402.  
  403.    NAME
  404.     SVD_GetWindowAddress
  405.  
  406.    SYNOPSIS
  407.  
  408.     struct Window *SVD_GetWindowAddress(APTR handle, future)
  409.     D0           -$5a            A1         A2
  410.  
  411.    FUNCTION
  412.  
  413.     While displaying, the Address of the DisplayWindow can be get
  414.     via this function.
  415.     See description there and example SourceCodes for more and
  416.     detailed information.
  417.  
  418.     This statement may not return a pointer to the real DisplayWindow,
  419.     if the SVDriver uses non-Intuition ways