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


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

.. manpage:: 3 ggiGetRayPos


Synopsis
--------

::

  #include <ggi/misc.h>

  int ggiGetRayPos(ggi_visual_t vis, int32_t* x, int32_t* 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 :man:`ggi-error(3)` 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, int32_t* x, int32_t* 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 :man:`ggi-error(3)` 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 :man:`ggi-error(3)` code.