home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 3 / goldfish_volume_3.bin / files / gfx / show / superview-lib / programmers / docs / svdriver_ref_eng.doc < prev    next >
Encoding:
Text File  |  1995-05-28  |  12.0 KB  |  513 lines
  1.  
  2.    $VER: SVDriver_Ref_ENG.doc V2.1 (18.2.95)
  3.  
  4.    © 1994-95 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.     Phone:  +49-271-331859 (weekdays after 18.00h)
  14.             +49-271-332147 (weekdays after 18.00h)
  15.     EMail:  Fido             Andreas Kleinert 2:2457/435.10
  16.             Usenet/InterNet  Andreas_Kleinert@superview.ftn.sub.org
  17.  
  18.       If nothing else works, try one of these Fido-InterNet gateways:
  19.  
  20.             Andreas_Kleinert@p10.f435.n2457.z2.fido.sub.org (in Germany)
  21.             Andreas_Kleinert@p10.f435.n2457.z2.fidonet.org  (USA or other)
  22.  
  23.  
  24.    * DO _NEVER_ ACCESS ANY SVDRIVERS DIRECTLY.
  25.    * DO NEVER BYPASS superview.library !
  26.  
  27.    THE FOLLOWING NOTES ARE ONLY FOR PROGRAMMERS OF SVDRIVERS :
  28.  
  29.    Here is a listing of the function set, which any of the version 1
  30.    SVDrivers does contain, in an Autodoc-like style of description :
  31.  
  32.         SVD_AllocHandle            ; since Version 1
  33.         SVD_FreeHandle
  34.         SVD_CloseDisplay
  35.         SVD_FreeResources
  36.         SVD_SetGfxBuffer
  37.         SVD_DisplayGfxBuffer
  38.         SVD_SetScreenType
  39.         SVD_SetWindowFlags
  40.         SVD_SetWindowIDCMP
  41.         SVD_GetScreenAddress
  42.         SVD_GetWindowAddress
  43.         SVD_GetModeList            ; since Version 2
  44.  
  45.  (you will never find any notes belonging to "BUGS", because any SVDriver
  46.   may have its own ...)
  47.  
  48. -----------------------------------------------------------------------------
  49.    Functions available since Version 1 :
  50. -----------------------------------------------------------------------------
  51.  
  52.    NAME
  53.         SVD_AllocHandle
  54.  
  55.    SYNOPSIS
  56.  
  57.         APTR SVD_AllocHandle(APTR future)
  58.         D0   -$1e            A1
  59.  
  60.    FUNCTION
  61.  
  62.         Allocates a handle for displaying a GfxBuffer via this SVDriver.
  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 SVDrivers.
  79.  
  80.    SEE ALSO
  81.  
  82.         SVD_FreeResources, SVD_FreeHandle
  83.  
  84. -----------------------------------------------------------------------------
  85.  
  86.    NAME
  87.         SVD_FreeHandle
  88.  
  89.    SYNOPSIS
  90.  
  91.         VOID SVD_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 SVD_AllocHandle before.
  98.  
  99.  
  100.        For programmers of SVDrivers :
  101.  
  102.        Note, that this function should call
  103.  
  104.           SVD_CloseDisplay(SVHandle);
  105.           SVD_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 SVDrivers.
  122.  
  123.    SEE ALSO
  124.  
  125.         SVD_AllocHandle, SVD_CloseDisplay, SVD_FreeResources
  126.  
  127. -----------------------------------------------------------------------------
  128.  
  129.    NAME
  130.         SVD_CloseDisplay
  131.  
  132.    SYNOPSIS
  133.  
  134.         VOID SVD_CloseDisplay(APTR handle)
  135.         D0   -$2a             A1
  136.  
  137.    FUNCTION
  138.  
  139.         Aborts showing the Graphic, indentified by the handle.
  140.         The Display-Screen is closed, but no other resources are given free.
  141.  
  142.    INPUT(S)
  143.  
  144.         handle - a valid handle
  145.  
  146.    RESULT
  147.  
  148.         -
  149.  
  150.    SINCE
  151.  
  152.         ... Version 1 SVDrivers.
  153.  
  154.    SEE ALSO
  155.  
  156.         SVD_FreeResources, SVD_FreeHandle
  157.  
  158. -----------------------------------------------------------------------------
  159.  
  160.    NAME
  161.         SVD_FreeResources
  162.  
  163.    SYNOPSIS
  164.  
  165.         VOID SVD_FreeResources(APTR handle)
  166.         D0   -$30              A1
  167.  
  168.    FUNCTION
  169.  
  170.         Frees all resources belonging to the specific Graphic,
  171.         indentified by the handle, which are not needed to just show it.
  172.         The Display will not be closed.
  173.  
  174.    INPUT(S)
  175.  
  176.         handle - a valid handle
  177.  
  178.    RESULT
  179.  
  180.         -
  181.  
  182.    SINCE
  183.  
  184.         ... Version 1 SVDrivers.
  185.  
  186.    SEE ALSO
  187.  
  188.         SVD_AllocHandle, SVD_CloseDisplay, SVD_FreeHandle
  189.  
  190. -----------------------------------------------------------------------------
  191.  
  192.    NAME
  193.         SVD_SetGfxBuffer
  194.  
  195.    SYNOPSIS
  196.  
  197.         ULONG SVD_SetGfxBuffer(APTR handle, struct SV_GfxBuffer *buffer,
  198.         D0    -$36             A1           A2
  199.  
  200.                                ULONG future)
  201.                                A3
  202.  
  203.    FUNCTION
  204.  
  205.         Initializes the given handle with a pointer to a SV_GfxBuffer, which
  206.         should be used with the next call of SVD_DisplayGfxBuffer (see there).
  207.  
  208.         This Buffer STILL HAS TO BE GIVEN FREE the way it has been allocated
  209.         (see documentation of SVObjects and superviewsupport.library)
  210.         and may still be displayed via SVD_DisplayGfxBuffer or saved
  211.         anywhere else.
  212.  
  213.    INPUT(S)
  214.  
  215.         handle    - a valid handle
  216.         buffer    - a pointer to a valid SV_GfxBuffer
  217.         future    - always NULL yet
  218.  
  219.    RESULT
  220.  
  221.         NULL or an adequate SVERR-Errorcode.
  222.  
  223.    SINCE
  224.  
  225.         ... Version 1 SVDrivers.
  226.  
  227.    SEE ALSO
  228.  
  229.         SVD_DisplayGfxBuffer
  230.  
  231. -----------------------------------------------------------------------------
  232.  
  233.    NAME
  234.         SVD_DisplayGfxBuffer
  235.  
  236.    SYNOPSIS
  237.  
  238.         ULONG SVD_DisplayGfxBuffer(APTR handle, future)
  239.         D0    -$3c                 A1           A2
  240.  
  241.    FUNCTION
  242.  
  243.         Displays the GfxBuffer (which has been set via SVD_SetGfxBuffer before)
  244.         in the way, which is native to this SVDriver (e.g. on an Intuition
  245.         Screen, an EGS-Screen or into NIL ...)
  246.  
  247.    INPUT(S)
  248.  
  249.         handle    - a valid handle
  250.         future    - always NULL yet
  251.  
  252.    RESULT
  253.  
  254.         NULL or an adequate SVERR-Errorcode.
  255.  
  256.    SINCE
  257.  
  258.         ... Version 1 SVDrivers.
  259.  
  260.    SEE ALSO
  261.  
  262.         SVD_SetGfxBuffer
  263.  
  264. -----------------------------------------------------------------------------
  265.  
  266.    NAME
  267.         SVD_SetScreenType
  268.  
  269.    SYNOPSIS
  270.  
  271.         ULONG SVD_SetScreenType(APTR handle, ULONG type, APTR future)
  272.         D0    -$42              A1           D1          A2
  273.  
  274.    FUNCTION
  275.  
  276.         Specifies, which ScreenType the Screen should have, on which the
  277.         graphic is to be displayed later.
  278.  
  279.         This statement may have no effect, if the SVDriver uses non-Intuition
  280.         ways of displaying or exporting the GfxBuffer (e.g. EGS.svdriver will
  281.         ignore this setting more or less).
  282.  
  283.    INPUT(S)
  284.  
  285.         handle - a valid handle
  286.         type   - a ScreenType descriptor, like e.g. CUSTOMSCREEN
  287.         future - always NULL yet
  288.  
  289.    RESULT
  290.  
  291.         NULL or an adequate SVERR-Errorcode.
  292.  
  293.    SINCE
  294.  
  295.         ... Version 1 SVDrivers.
  296.  
  297.    SEE ALSO
  298.  
  299.         SVD_GetScreenAddress
  300.  
  301. -----------------------------------------------------------------------------
  302.  
  303.    NAME
  304.         SVD_SetWindowFlags
  305.  
  306.    SYNOPSIS
  307.  
  308.         ULONG SVD_SetWindowFlags(APTR handle, ULONG flags, APTR future)
  309.         D0    -$48               A1           D1           A2
  310.  
  311.    FUNCTION
  312.  
  313.         Specifies, which Flags the Window should have, on which the
  314.         graphic is to be displayed later.
  315.  
  316.         This statement may have no effect, if the SVDriver uses non-Intuition
  317.         ways of displaying or exporting the GfxBuffer (e.g. EGS.svdriver will
  318.         ignore this setting more or less).
  319.  
  320.    INPUT(S)
  321.  
  322.         handle     - a valid handle
  323.         flags      - valid WindowFlags, like e.g. WFLG_BACKDROP
  324.         future     - always NULL yet
  325.  
  326.    RESULT
  327.  
  328.         NULL or an adequate SVERR-Errorcode.
  329.  
  330.    SINCE
  331.  
  332.         ... Version 1 SVDrivers.
  333.  
  334.    SEE ALSO
  335.  
  336.         SVD_SetWindowIDCMP, SVD_GetWindowAddress
  337.  
  338. -----------------------------------------------------------------------------
  339.  
  340.    NAME
  341.         SVD_SetWindowIDCMP
  342.  
  343.    SYNOPSIS
  344.  
  345.         ULONG SVD_SetWindowIDCMP(APTR handle, ULONG idcmp, APTR future)
  346.         D0    -$4e               A1           D1           A2
  347.  
  348.    FUNCTION
  349.  
  350.         Specifies, which IDCMP the Window should have, on which the
  351.         graphic is to be displayed later.
  352.  
  353.         This statement may have no effect, if the SVDriver uses non-Intuition
  354.         ways of displaying or exporting the GfxBuffer (e.g. EGS.svdriver will
  355.         ignore this setting more or less).
  356.  
  357.    INPUT(S)
  358.  
  359.         handle - a valid handle
  360.         idcmp  - a valid set of IDCMP-Flags
  361.         future - always NULL yet
  362.  
  363.    RESULT
  364.  
  365.         NULL or an adequate SVERR-Errorcode.
  366.  
  367.    SINCE
  368.  
  369.         ... Version 1 SVDrivers.
  370.  
  371.    SEE ALSO
  372.  
  373.         SVD_Show
  374.  
  375. -----------------------------------------------------------------------------
  376.  
  377.    NAME
  378.         SVD_GetScreenAddress
  379.  
  380.    SYNOPSIS
  381.  
  382.         struct Screen *SVD_GetScreenAddress(APTR handle, future)
  383.         D0             -$54                 A1           A2
  384.  
  385.    FUNCTION
  386.  
  387.         While displaying, the address of the DisplayScreen is returned
  388.         by this function.
  389.         See example SourceCodes for more and detailed information.
  390.  
  391.         This statement may not return a pointer to the real DisplayScreen,
  392.         if the SVDriver uses non-Intuition ways of displaying or exporting
  393.         the GfxBuffer (e.g. EGS.svdriver uses EGS-Screens, which are not
  394.         compatible with Intuition Screens).
  395.         So NULL or a pointer to a Dummy-Screen (Workbench-Screen) might be
  396.         returned sometimes.
  397.  
  398.    INPUT(S)
  399.  
  400.         handle - a valid handle
  401.         future - always NULL yet
  402.  
  403.    RESULT
  404.  
  405.         A valid ScreenPointer or NULL.
  406.  
  407.    SINCE
  408.  
  409.         ... Version 1 SVDrivers.
  410.  
  411.    SEE ALSO
  412.  
  413.         SVD_GetWindowAddress
  414.  
  415. -----------------------------------------------------------------------------
  416.  
  417.    NAME
  418.         SVD_GetWindowAddress
  419.  
  420.    SYNOPSIS
  421.  
  422.         struct Window *SVD_GetWindowAddress(APTR handle, future)
  423.         D0             -$5a                 A1           A2
  424.  
  425.    FUNCTION
  426.  
  427.         While displaying, the address of the DisplayWindows is returned
  428.         by this function.
  429.         See example SourceCodes for more and detailed information.
  430.  
  431.         This statement may not return a pointer to the real DisplayWindow,
  432.         if the SVDriver uses non-Intuition ways of displaying or exporting
  433.         the GfxBuffer (e.g. EGS.svdriver uses EGS-Windows, which are not
  434.         compatible with Intuition Windows).
  435.         So NULL or a pointer to a Dummy-Window (Custom-Window on Workbench)
  436.         might be returned sometimes.
  437.  
  438.    INPUT(S)
  439.  
  440.         handle - a valid handle
  441.         future - always NULL yet
  442.  
  443.    RESULT
  444.  
  445.         A valid WindowPointer or NULL.
  446.  
  447.    SINCE
  448.  
  449.         ... Version 1 SVDrivers.
  450.  
  451.    SEE ALSO
  452.  
  453.         SVD_GetScreenAddress
  454.  
  455. -----------------------------------------------------------------------------
  456.    Functions added with Version 2 :
  457. -----------------------------------------------------------------------------
  458.  
  459.    NAME
  460.         SVD_GetModeList
  461.  
  462.    SYNOPSIS
  463.  
  464.         ULONG SVD_GetModeList(APTR handle, struct SVModeList **modelist,
  465.         D0    -$60            A1           A2
  466.  
  467.                               struct SV_GfxBuffer *refbuf, ULONG future)
  468.                               A3                           A4
  469.    FUNCTION
  470.  
  471.         Tries to get an appropriate list of possible ScreenModes for this
  472.         GfxBuffer/SVDriver combination.
  473.  
  474.         If NULL is specified for the SV_GfxBuffer pointer, any possible
  475.         ScreenModes for this SVDriver will be returned.
  476.  
  477.  
  478.         Note: Any former SVModeList will be freed when calling this
  479.               function again. In general, delocation is done when
  480.               calling SVD_FreeHandle().
  481.  
  482.    INPUT(S)
  483.  
  484.         handle   - a valid handle
  485.         modelist - a pointer to a SVModeList pointer
  486.         refbuf   - a SV_GfxBuffer as "ScreenMode reference"
  487.         future   - always NULL yet
  488.  
  489.    RESULT
  490.  
  491.         NULL or an adequate SVERR-Errorcode.
  492.  
  493.    WARNING
  494.  
  495.         This function may be called at any time (even if already a
  496.         display has been opened) and has to take care, that calling
  497.         it more than once does not cause memory loss (free any old
  498.         lists before creating and returning the new one).
  499.  
  500.         This function does NOT interpret any internal GfxBuffer pointers.
  501.         It only checks the given "refbuf" (if not NULL).
  502.  
  503.    SINCE
  504.  
  505.         ... Version 2 SVDrivers.
  506.  
  507.    SEE ALSO
  508.  
  509.         -
  510.  
  511. -----------------------------------------------------------------------------
  512.  
  513.