Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
AG_TIME(3)		     Library Functions Manual		      AG_TIME(3)

NAME
     AG_Time -- agar time interface

SYNOPSIS
     #include <agar/core.h>

DESCRIPTION
     These  functions  provide a low-level interface to monotonically increasing
     time sources.  Different time backends may be  implemented  (see  "INTERNAL
     API" below).  Agar provides the following backends:

     agTimeOps_dummy	      No-op (timers will be unavailable).

     agTimeOps_gettimeofday   BSD-style gettimeofday() interface.

     agTimeOps_posix	      The POSIX clock_gettime() interface.

     agTimeOps_renderer       Monotonic  clock	which stops while graphical ren-
			      dering is performed.  This is useful for	applica-
			      tions performing offline rendering, where the ren-
			      der may be influenced by different threads relying
			      on  Agar	timers or AG_Delay() calls.  It requires
			      the POSIX clock_gettime() interface.

     agTimeOps_win32	      The MS Windows winmm API.

INTERFACE
     Uint32 AG_GetTicks(void)

     void AG_Delay(Uint32 t)

     void AG_SetTimeOps(const AG_TimeOps *ops)

     The AG_GetTicks() function returns the current time  in  ticks.   One  tick
     usually corresponds to one millisecond.

     The AG_Delay() function blocks the current thread, waiting at least t ticks
     before returning.	The exact amount of time which AG_Delay() waits is plat-
     form and backend dependent.

     The AG_SetTimeOps() function selects a time backend (see below).

BACKEND INTERFACE
     The argument to AG_SetTimeOps() should point to the following structure:

     typedef struct ag_time_ops {
	     const char *name;
	     void   (*Init)(void);
	     void   (*Destroy)(void);
	     Uint32 (*GetTicks)(void);
	     void   (*Delay)(Uint32);
     } AG_TimeOps;

     Init()  performs any necessary initialization.  Destroy() cleans up any al-
     located resources.

     The GetTicks() operation is the backend to AG_GetTicks() and Delay() is the
     backend to AG_Delay().

EXAMPLES
     The following code uses AG_GetTicks() to estimate the  running  time  of  a
     routine:

	   Uint32 t1, t2;

	   t1 = AG_GetTicks();
	   MyFunc();
	   t2 = AG_GetTicks();

	   AG_Verbose("MyFunc() ran for %u ticks\n",
	       t2 - t1);

     The    following	 code	selects   the	rendering-aware   time	 backend
     agTimeOps_renderer if it's available:

	   #include <agar/config/have_clock_gettime.h>
	   #include <agar/config/have_pthreads.h>

	   #if defined(HAVE_CLOCK_GETTIME) && \
	       defined(HAVE_PTHREADS)
	   AG_SetTimeOps(&agTimeOps_renderer);
	   #endif

SEE ALSO
     AG_Intro(3), AG_Timer(3)

HISTORY
     The AG_Time interface first appeared in Agar 1.3.4.

Agar 1.7			December 21, 2022		      AG_TIME(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Time&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help