========================
LibGGIMisc Documentation
========================


LibGGIMisc Functions
====================


Find out where the raster beam is
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiGetRayPos


Synopsis
--------

::

  #include <ggi/misc.h>

  int ggiGetRayPos(ggi_visual_t vis, sint32* x, sint32* y);


Description
-----------

Though currently only implemented via matroxfb, this function will
retrieve the current position of the raster beam on a display that
uses a cathode ray tube, or resembles such internally.  Because it has
not been implemented and put into widespread use, there may be API
fluctuation as to exactly what units :p:`x`, :p:`y` are in, especially
on displays using doublescanning modes.  In addition to numerical
values, the following values can be returned in either dimension:
`GGI_RP_BORDER` means the raster is in the border of the screen;
`GGI_RP_BLANK` means the raster is past the border and is turned off;
`GGI_RP_SYNC` means the raster is retracing to the top of the screen.


Return value
------------

`0` for OK, otherwise an error code.


See Also
--------

:man:`ggiWaitRayPos(3)`



Wait for the raster to reach a point
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiWaitRayPos

Synopsis
--------

::

  #include <ggi/misc.h>

  int ggiWaitRayPos(ggi_visual_t src, sint32* x, sint32* y);


Description
-----------


`ggiWaitRayPos` will wait, as best supported by the target, until the
raster reaches a certain point on the screen.  Actual integer
coordinates don't mean anything under current implementations, and the
units the coordinates are provided in haven't been firmly
decided. Instead, use one of the following macros: `GGI_RP_BORDER`
means the raster is in the border of the screen; `GGI_RP_BLANK` means
the raster is past the border and is turned off; `GGI_RP_SYNC` means
the raster is retracing to the top of the screen; `GGI_RP_DONTCARE`
means you don't care where the raster is in this direction.


Return value
------------


`0` for OK, otherwise an error code.  In the event that there is an
error, it is most likely that the implementation on the given target
is limited.  In this case, the parameters :p:`x`,:p:`y` will be
assigned values equal to one of the above macros, which should work on
the target, supposing using those values actually accomplishes what
you want to do.


See Also
--------


:man:`ggiGetRayPos(3)`





Set the hardware split line feature
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiSetSplitline

Synopsis
--------

::

  #include <ggi/misc.h>

  int ggiSetSplitline(ggi_visual_t vis, int y);


Description
-----------

Original VGA adaptors in order to be efficient when displaying
vertically scrolling scenery implemented a feature that, when used in
combination with the display origin, could cause the screen to wrap.
This essentially means you can take the framebuffer and seamlessly
join the top edge to the bottom edge, creating a cylinder of data that
you could scroll up or down without actually performing memory move
operations.  This functions sets the :p:`y` coordinate at which the
screen wraps back.


Return value
------------

`0` for OK, otherwise an error code.



LibGGIMisc libraries and utilities
==================================


Add-on to LibGGI for extraneous features
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 7 libggimisc


Description
-----------


`LibGGIMisc` is a LibGGI extension implementing
support for a range of hard to categorize features.


LibGGIMisc consists of a main library (`libggimisc.so`) and a few
(there should be more) dynamic drivers. At runtime, the library loads
the necessary drivers taking hints from the graphics device if
necessary.


See Also
--------

:man:`ggiWaitRayPos(3)`, :man:`ggiGetRayPos(3)`,
:man:`ggiSetSplitline(3)`
