LibGGIOVL Functions
===================

Some are not documented yet:
ggiOvlClearMotorProperties,
ggiOvlClearCarbProperties,
ggiOvlClearTankProperties,
ggiOvlDestroyOvl,
ggiOvlUntie (goes with tie),
ggiOvlEnable,
ggiOvlDisable,
ggiOvlIsEnabled,
ggiOvlSetImage.
Moreover, the GetFlag is missing in the header and the page needs to
be completed


Extension management
~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiOvlInit ggiOvlExit ggiOvlAttach ggiOvlDetach

Synopsis
--------

::

  #include <ggi/ovl.h>
  
  int ggiOvlInit(void);
  
  int ggiOvlExit(void);

  int ggiOvlAttach(ggi_visual_t vis, ggiGA_resource_list *reqlist);
  
  int ggiOvlDetach(ggi_visual_t vis);


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

`ggiOvlInit` initializes the library. This function must be called
before using other LibOvl functions; otherwise the results will be undefined.

`ggiOvlExit` uninitializes the library (after being initialized by
`ggiOvlInit`) and automatically cleanup if necessary.  This should be
called after an application is finished with the library.  If any
LibOvl functions are called after the library has been uninitialized,
the results will be undefined.

`ggiOvlInit` allows multiple invocations.  A reference count is
maintained, and to completely uninitialize the library, `ggiOvlExit`
must be called as many times as `ggiOvlInit` has been called
beforehand.


`ggiOvlAttach` extends a visual such that the LibOvl API may be used
on the visual handle.  This function must be called before using other
LibOvl functions on the visual handle.  The parameter reslist is a
pointer to a LibGAlloc resource list kept by the application, and such
an object must exist and be passed here in order to use the
simple-form `ggiOvlCreate*` functions.

Note that not all LibGGI visuals support LibOvl, so checking the
return code of `ggiOvlAttach` is important.

`ggiOvlDetach` cleans up all state associated with using the LibOvl
API on this visual.  The visual is stripped of any active LibOvl
objects.  Note, however, that the objects themselves are not currently
guaranteed to be destroyed and may still exist, consuming resources.
Behavior of these objects is at this point undefined.  They should be
destroyed before calling `ggiOvlDetach`.


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


`ggiOvlInit`, `ggiOvlAttach` and `ggiOvlDetach` return `0` for OK,
otherwise an error code.


`ggiOvlExit` returns:

`0`
	after successfully cleaning up,

`>0`
	the number of 'open' `ggiOvlInit` calls, if there has been
	more than one call to `ggiOvlInit`.  As `ggiOvlInit` and
	`ggiOvlExit` must be used in properly nested pairs, e.g. the
	first `ggiOvlExit` after two `ggiOvlInit`\ s will return 1.

`<0` 
	error, especially if more `ggiOvlExit` calls have been done
	than `ggiOvlInit` calls.


Example
-------

Activate LibOvl such that the ggiOvlCreate* functions work::

  ggiGA_resource_list reslist;

  reslist = NULL;
  if (!ggiOvlInit()) { 
      exit(EXIT_FAILURE);  /* can't start! */
  }
 if (!ggiOvlAttach(vis, &reslist)) {
      ggiOvlExit();
      exit(EXIT_FAILURE);  /* can't attach OVL! */
 }

  /* Do some libovl stuff */

  ggiOvlDetach(vis);
  ggiOvlExit();



Allocate and activate a video overlay resource on the fly
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiOvlCreateSprite ggiOvlCreateWindow ggiOvlCreateVideo ggiOvlCreate ggiOvlCreateInGroup

Synopsis
--------

::

  #include <ggi/ovl.h>

  ggiOvl_t ggiOvlCreateSprite(ggi_visual_t vis,
			      int width, int height,
			      enum ggiGA_resource_type subtype,
			      enum ggiOvl_flags flags);

  ggiOvl_t ggiOvlCreateWindow(ggi_visual_t vis,
			      int width, int height,
			      enum ggiGA_resource_type subtype,
			      enum ggiOvl_flags flags);

  ggiOvl_t ggiOvlCreateVideo(ggi_visual_t vis,
	  		     int width, int height,
			     enum ggiGA_resource_type subtype,
			     enum ggiOvl_flags flags);


  ggiOvl_t ggiOvlCreate(ggi_visual_t vis,
			struct ggiGA_resource_props *prop_motor,
		        struct ggiGA_resource_props *prop_carb,
		        struct ggiGA_resource_props *prop_tank,
		        enum ggiGA_resource_type type);

  ggiOvl_t ggiOvlCreateInGroup(ggi_visual_t vis, ggiOvl_t group_leader,
			       struct ggiGA_resource_props *prop_tank);


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

`ggiOvlCreateSprite` allocates and creates a Sprite object for use on
the given visual.  The parameter subtype allows choosing a particular
type of sprite: ``GA_RT_SPRITE_POINTER`` will find hardware mouse
cursors, ``GA_RT_SPRITE_CURSOR`` will find hardware text cursors,
``GA_RT_SPRITE_SPRITE` will find a true sprite, if one exists, before
trying one of the former two resources.  The value zero, or the value
``GA_RT_SPRITE_DONTCARE``, will get any sprite available regardless of
it's type.  For resources of subtype ``GA_RT_SPRITE_POINTER``, the
flag value ``OVL_FLAGS_AUTOTRACK`` designates that the target has the
ability to automatically move the mouse cursor based on user input,
transparent the LibGII input handler.  Some targets, in fact, must
always do so, and in those cases ggiOvlCreateSprite will fail unless
the flag value ``OVL_FLAGS_AUTOTRACK`` is set.



`ggiOvlCreateVideo` allocates and creates a video overlay area for use
on the given visual.  The video overlay may or may not require the use
of video card RAM, depending on the display subsystem.  If it does,
the RAM is set aside for use by this resource.  The parameter subtype
allows choosing a particular type of video overlay.  Currently there
is only one type implemented, ``GA_RT_VIDEO_MOTION``.  The value zero,
or the value ``GA_RT_VIDEO_DONTCARE`` will get any video overlay
available regardless of its type, which is of dubious usefulness since
video overlay windows vary widely in their application.


`ggiOvlCreateWindow` allocates and creates a viewport or other area
which provides hardware translation of pixel format or pixel layout.
The parameter subtype allows choosing a particular type of window:
``GA_RT_WINDOW_YUV`` will find overlays which allow you to store
pixels in a certain screen area in untranslated YUV colorspace, yet
still display them normally to the user; ``GA_RT_WINDOW_MMU`` will
create a memory translation overlay, which allows you to access a
sub-area of the framebuffer as if it were its own framebuffer, with
memory layout translated by the display subsystem (think of this as a
directbuffer for display-sub.)  The value zero, or the value
``GA_RT_WINDOW_DONTCARE``, will get any overlay window available
regardless of its type, which is of dubious utility since overlay
windows vary widely in their application.


In the above three functions, the width and height parameters request
a minimum visual size of the object.  This size is given in pixels.
If sub-pixel accuracy is desired at creation time, you should use
`ggiOvlCreate`.


`ggiOvlCreate` and ggiOvlCreateInGroup are provided for advanced
users.  The three parameters :p:`props_motor`, :p:`props_carb`, and
:p:`props_tank` represent LibGAlloc properties structures, and are
documented in the LibGAlloc documentation.  The parameter type selects
the type of the resource. `ggiOvlCreateInGroup` allows the creation of
new members of groups of resources that share something, e.g. a set of
sprites which share a priority engine.  The parameter group_leader can
actually be any `ggiOvl_t` which is also in that group.


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


For all five functions a `ggiOvl_t` object handle will be returned if
the overlay was successfully allocated and activated.  On error,
`NULL` will be returned.


Examples
--------

Activate a mouse cursor::

  mouseptr = ggiOvlCreateSprite(vis, 64, 64, 
		                GA_RT_SPRITE_POINTER, OVL_FLAGS_AUTOTRACK);
  if(mouseptr == NULL) {
	autotrack = 0;
	mouseptr = ggiOvlCreateSprite(vis, 64, 64, GA_RT_SPRITE_POINTER, 0);
	if (mouseptr == NULL) {
		/* Cannot get a mouse cursor. */
	}
  }
  else {
	autotrack = 1;
  }


Add a request for a graphics overlay to a LibGAlloc request list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiOvlAdd ggiOvlAdd2Group

Synopsis
--------

::

  #include <ggi/ovl.h>

  int ggiOvlAdd(ggiGA_resource_list *reqlist,
	        struct ggiGA_resource_props *prop_motor,
	        struct ggiGA_resource_props *prop_carb,
	        struct ggiGA_resource_props *prop_tank,
	        struct ggiGA_resource_props *prop_tank_cap,
	        enum ggiGA_resource_type type,
	        ggiGA_resource_handle *handle_motor,
	        ggiGA_resource_handle *handle_carb,
	        ggiGA_resource_handle *handle_tank,
	        ggiGA_resource_handle *handle_tank_cap);

  int ggiOvlAdd2Group(ggiGA_resource_list *reqlist,
		      struct ggiGA_resource_props *prop_tank,
		      struct ggiGA_resource_props *prop_tank_cap,
		      ggiGA_resource_handle handle_carb,
		      ggiGA_resource_handle *handle_tank,
		      ggiGA_resource_handle *handle_tank_cap);

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

The `ggiOvlAdd` functions are LibOvl's interface to LibGAlloc. In both
functions, the parameter reqlist refers to a LibGAlloc request list,
and the parameter :p:`handle` returns a handle to the newly added
request.

`ggiOvlAdd` supplies a more convenient way to attach a request for a
graphics overlay than doing so by hand with LibGAlloc functions.  The
parameters prop_motor and prop_tank are used to create a motor and
tank resource, respectively, for the overlay.  The parameter
:p:`prop_tank_cap`, if not ``NULL``, creates a cap resource for the
added tank, to prevent any ``GGI_AUTO``\ s contained therein from
absorbing excessive graphics resources.  The parameter prop_carb
creates a carb resource which is then attached as appropriate to the
motor and to the tank, thus fully defining the resource.  All
resources are added with the resource type given in the parameter
:p:`type`.  The last four parameters are used to return handles to the
resulting resources as they appear in the resource list reqlist.

`ggiOvlAdd2Group` is used to add a request for a graphics overlay
resource based on a previously added resource.  This is most commonly
used to allocate Z or alpha buffers for overlays which keep this data
in a separate area.  The parameter :p:`handle_carb` refers to a carb
resource in the list, for example, one returned in the
:p:`handle_carb` parameter to `ggiOvlAdd`, and is used to find the
group to which the new resource is to be joined.  The :p:`prop_tank`
and :p:`prop_tank_cap` parameters work as decribed for `ggiOvlAdd`.


In comparing these functions to the `ggiOvlCreate*` function group,
it is useful to note that the :p:`flags` parameter of the `ggiOvlCreate*`
functions simply alters the member `.flags` in the motor properties.


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

Both functions return `0` on success, or a negative value if an error
occurred.


Examples
--------

Add a request for two sprites in the same sprite engine::

  ggiGA_resource_list reqlist = NULL;
  struct ggiGA_resource_properties pm, pc, pt;
  ggiGA_resource_handle m, c, t1, t2;

  ggiOvlClearMotorProperties(&pm);
  ggiOvlClearCarbProperties(&pc);
  ggiOvlClearTankProperties(&pt);

  pt.size.area.x = pt.size.area.y = 64;

  ggiOvlAdd(vis, reqlist, 
          &pm, &pc, &pt, NULL, GA_RT_SPRITE_SPRITE, 
          &m,  &c,  &t1, NULL);
  ggiOvlAdd2Group(vis, reqlist, &pt, NULL, c, &t2, NULL);


See Also
--------

:man:`ggiOvlCreate(3)`, :man:`ggiOvlAdd(3)`



Activate an allocated graphics overlay resource
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiOvlTie ggiOvlUntie

Synopsis
--------

::

  #include <ggi/ovl.h>

  ggiOvl_t ggiOvlTie(ggi_visual_t vis,
		     ggiGA_resource_handle handle_motor,
		     ggiGA_resource_handle handle_carb,
		     ggiGA_resource_handle handle_tank);

  int ggiOvlUntie(ggiOvl_t *ovl);


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

`ggiOvlTie` creates a `ggiOvl_t` object from approved resource
handles.

After creation, the resource will be hidden, any color lookup
tables in the object will have all colors set to black, it will
be moved to the lowest slot in any priority group in which it may
be a member, and any pixel data which the object may contain will 
be in an undefined state.


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

`ggiOvlTie` returns a newly allocated ggiOvl_t object, or NULL on
failure.

Examples
--------

Tie a resource using the return values of ggiOvlAdd::

  ggiGASet(vis, reqlist, &reslist);  /* get resources from LibGAlloc */
  m  = ggiGAHandle(vis, reslist, reqlist, m);
  c  = ggiGAHandle(vis, reslist, reqlist, c);
  t1 = ggiGAHandle(vis, reslist, reqlist, t1);
  overlay = ggiOvlTie(vis, m, c, t1);

See Also
--------

:man:`ggiOvlAdd(3)`



Set the display priority of an overlay within its group
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiOvlHide ggiOvlIsHidden ggiOvlShow ggiOvlSetPriority ggiOvlGetPriority

Synopsis
--------

::

  #include <ggi/ovl.h>

  int ggiOvlHide(ggiOvl_t ovl);

  int ggiOvlIsHidden(ggiOvl_t ovl);

  int ggiOvlShow(ggiOvl_t ovl);

  int ggiOvlSetPriority(ggiOvl_t ovl, uint32 slot, int swap);

  int ggiOvlGetPriority(ggiOvl_t ovl, uint32 *slot);


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

`ggiOvlHide` turns off display of a graphics overlay so it cannot be
seen.  `ggiOvlShow` will cause the overlay to be turned on such that,
as long as it is not obscured by another overlay or positioned, sized,
colored, or filtered in such a way that makes it effectively
invisible, it will be visible to the user.  `ggiOvlIsHidden` returns a
positive value if an overlay has the potential to be seen, or a value
of zero if the overlay has been turned off with `ggiOvlHide`.  That is
to say, `ggiOvlIsHidden` will *not* return a positive value if the
overlay has been activated with `ggiOvlShow` but is obscured by
another overlay, or is for some other reason not visible to the user.


`ggiOvlSetPriority` and `ggiOvlGetPriority` sets or gets the priority
slot of an overlay which is a member of a group, e.g. a sprite engine.
An overlay in a higher priority slot will appear to be in front of
overlays in lower priority slots.  Overlays with negative priorities
are hidden from view.  The parameter :p:`swap`, if set to 1, will
cause the overlay which currently occupies that priority slot to
exchange priorities with the overlay ovl, or if :p:`swap` is set to 0,
if there is an overlay currently residing in the requested slot, it
will be moved to a slot with a negative number thus causing it to be
hidden.  Values other than one or zero for the parameter :p:`swap` are
reserved for future use.

For `ggiOvlSetPriority`, the special slot value of ``OVL_SLOT_FIND``
will look for an unoccupied slot in the priority group, starting at
the highest priority, and if found, will put ovl in that slot.
Otherwise, the ovl will be left in its current slot and
`ggiOvlSetPriority` fails.


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

Except for `ggiOvlIsHidden`, the return value for which is described
above, all functions return zero on success or a negative value on
failure.


See Also
--------

:man:`ggiOvlMove(3)`



Position, resize and zoom a graphics overlay
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiOvlSetPos ggiOvlMove ggiOvlGetPos ggiOvlSetSize ggiOvlGetSize ggiOvlSetLense ggiOvlGetLense ggiOvlSetVals

Synopsis
--------

::

  #include <ggi/ovl.h>

  int ggiOvlSetPos(ggiOvl_t ovl, long x, long y);

  int ggiOvlMove(ggiOvl_t ovl, long x, long y);

  int ggiOvlGetPos(ggiOvl_t ovl, long *x, long *y);

  int ggiOvlSetSize(ggiOvl_t ovl, long w, long h);

  int ggiOvlGetSize(ggiOvl_t ovl, long *x, long *y);

  int ggiOvlSetLense(ggiOvl_t ovl, long x, long y, long w, long h);

  int ggiOvlGetLense(ggiOvl_t ovl, long *x, long *y, long *w, long *h);

  int ggiOvlSetVals(ggiOvl_t ovl, long x, long y, long w, long h,
		    long lx, long ly, long lw, long lh);


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

.. important::

   all the coordinates and sizes are given in the units which were
   last set with the function ggiOvlSetCoordBase.  In addition, where
   noted below, coordinates are offset by the values last passed to
   `ggiOvlSetCoordBase`.  New resources, opon which
   `ggiOvlSetCoordbase` has never been used, start with their point of
   origin at the top left corner of the visual, and use the same units
   that were used to negotiate them via the `ggiOvlAdd*` or
   `ggiOvlCreate*` functions.  If you didn't specifically ask for
   certain units, then you should call `ggiOvlSetCoordBase` to set the
   desired units before attempting to use these functions.


`ggiOvlSetPos` positions the graphics overlay with the top left corner
at the given coordinates :p:`x` and :p:`y`.  The actual coordinates
used may be altered by the target subsystem if their are restrictions
on the placement of the resource.  `ggiOvlGetPos` will read the actual
position of the resource into the offered parameters :p:`x` and
:p:`y`.  `ggiOvlMove` is just another name for `ggiOvlSetPos`.  The
*lense* origin (see below) is interpolated to match the new position.


`ggiOvlSetSize` alters the visible size of a graphics overlay.  The
actual sizes used may be altered by the target subsystem if their are
restrictions on the pplacement of the resource.  `ggiOvlGetSize` will
read the actual position of the resource into the offered parameters
:p:`x` and :p:`y`.  The *lense* parameters (see below) are *not*
interpolated to the new size of the resource, and as such more of the
contents of the resource may be displayed.


`ggiOvlSetLense` alters the contents displayed inside the overlay on
resources which support zooming, tesslation, and panning.  The
parameters are given in the same units as those of the above five
functions, and if the contents are not to be panned or zoomed, :p:`x`,
:p:`y` will have the same values as last supplied to `ggiOvlSetPos`
and :p:`w`, :p:`h` will have the same values as last supplied to
`ggiOvlSetLense`.  Their usage is best described by example, see
below.


`ggiOvlSetVals` is used to set all the positioning and lense
parameters at the same time.  It is recommended to use this function,
rather than the above, when you need to perform a combination of
positioning, sizing, or zooming, operations on the overlay, for two
reasons: Firstly, if you are setting these parameters on an overlay
which is not hidden, this will likely induce less user-visible
artifacts; Secondly, some resources may not support the intermediate
states you traverse by using combinations of the other functions
above, and you may find they fail to actually implement the requested
changes.


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

All functions return 0 on success, or a negative value if an error
occurred.


Examples
--------

Move, zoom, and pan a video overlay::

  long sizex, sizey, posx, posy;
  ggi_mode mode;

  ggiGetMode(vis, &mode);

  /* Set the units to millimeters */
  ggiOvlSetCoordBase(ovl, GA_COORBASE_MILLIMETERS, 0, 0, 0, 0);

  /* Get the current size of the overlay */
  ggiOvlGetSize(ovl, &sizex, &sizey);

  err = ggiOvlMove(video,(mode.size.x - sizex)/2,(mode.size.y - sizey)/2));
  if (err) {
	fprintf(stderr, "Could not center the video display\n");
  }

  /* Get the current position of the overlay, 
   which may be slightly off from the above. */
  ggiOvlGetPos(ovl, &posx, &posy);

  /* Zoom the contents of the overlay to twice their normal size. */
  ggiOvlSetLense(ovl, posx, posy, sizex * 2, sizey * 2);

  /* Slowly pan over from the top left quadrant of the video image, 
   where we are now, to the lower right quadrant */
  for (i = 100; i > 0; i++) {
	ggiOvlSetLense(ovl, posx + sizex * i/ 100, posy + sizey * i/100, 
		    sizex * 2, sizey * 2);
	usleep(10000);
  }



Set the units and point of origin used when positioning an overlay
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiOvlSetCoordBase

Synopsis
--------

::

  #include <ggi/ggi.h>

  int ggiOvlSetCoordBase(ggiOvl_t ovl, enum ggi_ll_coordbase units,
		         long x, long y, long w, long h);

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


`ggiOvlSetCoordBase` sets the units used by future calls to `ggiOvl*`
functions on the provided object ovl, not including the :p:`x`,
:p:`y`, :p:`w`, :p:`h` parameters passed in the current call, which
are subject to translation from any coordinate base which was set with
a previous call to this function.

The parameter units decides the units that will be passed from this
point forward to LibOvl functions such as ggiOvlSetPos and
ggiOvlSetSize.  It may contain any of the following self-descriptive
values: ``LL_COORDBASE_PIXEL``, ``LL_COORDBASE_DOT``,
``LL_COORDBASE_MILLIMETER``, ``LL_COORDBASE_MICROMETER``,
``LL_COORDBASE_1_64_INCH``.

These values may be combined with a few bit flags: 

``LL_COORDBASE_RESET``
    causes the parameters in the current call to be interperated as
    though the resource was newly initialized, e.g.  no offsets are
    applied, and the units are in pixels.

``LL_COORDBASE_SUBUNIT``
    alters the scale to match any underlying natural unit which the
    resource has as defined in the LibGAlloc resource properties of
    ovl's motor resource.  This is only useful to deal with some very
    platform-specific applications.


The parameters :p:`x`, :p`y` set the origin offset for the object
:p:`ovl`. Coordinates passed to any future calls on ovl will be
subject to translation from this point of reference.  The parameters
:p:`w`, :p:`h` are analogous to that for sizing operations; generally
you should leave them alone by setting them to 0; most people will
never need them.


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

`ggiOvlSetCoordBase` returns 0 on success or a negative error
value on failure.


Examples
--------


Center a sprite at 50mm, 50mm and spiral it out from there::

  ggiOvlSetCoordBase(GA_COORDBASE_MILLIMETERS, 0, 0, 0, 0);
  ggiOvlGetSize(sprite, &sx, &sy);
  ggiOvlSetCoordBase(ovl, GA_COORDBASE_RESET, 50 - sx/2, 50 - sy/2, 0, 0);
  for (i = 0; i < 500; i++) {
	/* Note lack of "+ offset" in below.  Handy, eh? */
	ggiOvlSetPos(ovl, sin(i/100) * i / 10, cos(i/100) * i / 10);
  }


See Also
--------

:man:`ggiOvlSetFlags(3)`


Represent the data inside an overlay with a LibBuf object
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiOvl2Buf

Synopsis
--------

::

  #include <ggi/ovl.h>
  #include <ggi/buf.h>

  void *ggiOvl2Buf(ggiOvl_t ovl);

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

`ggiOvl2Buf` creates a LibBuf object corresponding to the LibGGIOvl
object :p:`ovl`.  In order to keep the libraries separate on the API
level, you must cast the returned void* pointer to a LibGGIBuf
`ggiBuf_t` yourself.  For resources with data buffers, such as sprite
bitmaps, the LibBuf_t object can be used as a lightweight mechanism
(vs. opening a new visual with `ggiOvl2Vis`) to load data to/from the
data buffer, or to create ancillary buffers for the overlay.  For
certain other resources, a LibGGIBuf object may be useful for use-time
(vs resource creation-time) configuration of Alpha blending rules, and
other such features not accessible through `ggiOvlSetFlags`.


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

`ggiOvl2Buf` returns a `void*` pointer which must be cast to type
`ggiBuf_t`, or `NULL` if an error occured.


Access an overlay as a LibGGI visual; load data into an overlay
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiOvl2Vis ggiOvlLoadVis

Synopsis
--------

::

  #include <ggi/ovl.h>

  ggi_visual_t ggiOvl2Vis(ggiOvl_t ovl);
  
  int ggiOvlLoadVis(ggiOvl_t ovl, int x, int y, int w, int h);


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

`ggiOvl2Vis` creates a LibGGI visual handle which may be used to draw
in the object using basic LibGGI primitives, to manipulate the
overlay's color pallette if it has one, gain directbuffer access to
the overlay's data if such access is allowed, and many other fun
and/or abusive things.


The created visual is not automatically attached to any of the
extension libraries of the parent visual.  There may be restrictions
on which extensions it may be attached to.  These restrictions will be
fully enumerated in the `ggiClone` function which will be added to
LibGGI during it's 3.0 release cycle.


Caveat: not all overlays were meant to be used as visuals.  Depending
on the nature of the overlay, and how useful/practical converting it
to a visual is, you may find that the resulting visual performs
slowly, or that certain LibGGI primitives fail with an error code, or
even that `ggiOvl2Vis` fails entirely in the first place.  Consider
using the more lightweight function `ggiOvl2Buf`.


In a similar manner to `ggiOpen`, arguments to the back-end target may
be passed via additional parameters.


The function `ggiOvlLoadVis` is a rudimentary function for loading an
image into an overlay from an area of the visual to which the overlay
belongs.  Only normal color data (not alpha/Z data) may be loaded in
this fashion, and no interpolation or scaling is done.  This function
is not guaranteed to be particularly fast, but will process color
space conversion as appropriate, and will be more universally
available than `ggiOvl2Vis` or `ggiOvl2Buf`.  The parameters
:p:`x`,:p:`y` and :p:`w`, :p:`h` represent coordinates in pixels of a
rectangle in the visual from which to load the data.


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

`ggiOvl2Vis` returns a `ggi_visual_t` handle, or `NULL` if an error
occured. `ggiOvlLoadVis` returns `0` (GGI_OK) on success or a negative
error code on failure.


Change use-time features of an overlay
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. manpage:: 3 ggiOvlSetFlags ggiOvlGetFlags

Synopsis
--------

::
  
  #include <ggi/ovl.h>

  int ggiOvlSetFlags(ggiOvl_t, unsigned int flags);

  int ggiOvlGetFlags(ggiOvl_t, unsigned int flags);

