------------------------------------------------------------------------------
-- --
-- Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet --
-- Copyright (C) 2000-2014, AdaCore --
-- --
-- This library is free software; you can redistribute it and/or modify it --
-- under terms of the GNU General Public License as published by the Free --
-- Software Foundation; either version 3, or (at your option) any later --
-- version. This library is distributed in the hope that it will be useful, --
-- but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHAN- --
-- TABILITY or FITNESS FOR A PARTICULAR PURPOSE. --
-- --
-- As a special exception under Section 7 of GPL version 3, you are granted --
-- additional permissions described in the GCC Runtime Library Exception, --
-- version 3.1, as published by the Free Software Foundation. --
-- --
-- You should have received a copy of the GNU General Public License and --
-- a copy of the GCC Runtime Library Exception along with this program; --
-- see the files COPYING3 and COPYING.RUNTIME respectively. If not, see --
-- <http://www.gnu.org/licenses/>. --
-- --
------------------------------------------------------------------------------
-- <description>
-- A Gdk.Frame_Clock.Gdk_Frame_Clock tells the application when to update and
-- repaint a window. This may be synced to the vertical refresh rate of the
-- monitor, for example. Even when the frame clock uses a simple timer rather
-- than a hardware-based vertical sync, the frame clock helps because it
-- ensures everything paints at the same time (reducing the total number of
-- frames). The frame clock can also automatically stop painting when it knows
-- the frames will not be visible, or scale back animation framerates.
--
-- Gdk.Frame_Clock.Gdk_Frame_Clock is designed to be compatible with an
-- OpenGL-based implementation or with mozRequestAnimationFrame in Firefox,
-- for example.
--
-- A frame clock is idle until someone requests a frame with
-- Gdk.Frame_Clock.Request_Phase. At some later point that makes sense for the
-- synchronization being implemented, the clock will process a frame and emit
-- signals for each phase that has been requested. (See the signals of the
-- Gdk.Frame_Clock.Gdk_Frame_Clock class for documentation of the phases.
-- Gdk.Frame_Clock.Gdk_Frame_Clock_Phase_Update and the
-- Gdk.Frame_Clock.Gdk_Frame_Clock::update signal are most interesting for
-- application writers, and are used to update the animations, using the frame
-- time given by Gdk.Frame_Clock.Get_Frame_Time.
--
-- The frame time is reported in microseconds and generally in the same
-- timescale as g_get_monotonic_time, however, it is not the same as
-- g_get_monotonic_time. The frame time does not advance during the time a
-- frame is being painted, and outside of a frame, an attempt is made so that
-- all calls to Gdk.Frame_Clock.Get_Frame_Time that are called at a "similar"
-- time get the same value. This means that if different animations are timed
-- by looking at the difference in time between an initial value from
-- Gdk.Frame_Clock.Get_Frame_Time and the value inside the
-- Gdk.Frame_Clock.Gdk_Frame_Clock::update signal of the clock, they will stay
-- exactly synchronized.
--
-- </description>
pragma Ada_2005;
pragma Warnings (Off, "*is already use-visible*");
with Gdk.Frame_Timings; use Gdk.Frame_Timings;
with Glib; use Glib;
with Glib.Generic_Properties; use Glib.Generic_Properties;
with Glib.Object; use Glib.Object;
package Gdk.Frame_Clock is
type Gdk_Frame_Clock_Record is new GObject_Record with null record;
type Gdk_Frame_Clock is access all Gdk_Frame_Clock_Record'Class;
type Gdk_Frame_Clock_Phase is mod 2 ** Integer'Size;
pragma Convention (C, Gdk_Frame_Clock_Phase);
-- Gdk.Frame_Clock.Gdk_Frame_Clock_Phase is used to represent the
-- different paint clock phases that can be requested. The elements of the
-- enumeration correspond to the signals of Gdk_Paint_Clock.
Gdk_Frame_Clock_Phase_None : constant Gdk_Frame_Clock_Phase := 0;
Gdk_Frame_Clock_Phase_Flush_Events : constant Gdk_Frame_Clock_Phase := 1;
Gdk_Frame_Clock_Phase_Before_Paint : constant Gdk_Frame_Clock_Phase := 2;
Gdk_Frame_Clock_Phase_Update : constant Gdk_Frame_Clock_Phase := 4;
Gdk_Frame_Clock_Phase_Layout : constant Gdk_Frame_Clock_Phase := 8;
Gdk_Frame_Clock_Phase_Paint : constant Gdk_Frame_Clock_Phase := 16;
Gdk_Frame_Clock_Phase_Resume_Events : constant Gdk_Frame_Clock_Phase := 32;
Gdk_Frame_Clock_Phase_After_Paint : constant Gdk_Frame_Clock_Phase := 64;
----------------------------
-- Enumeration Properties --
----------------------------
package Gdk_Frame_Clock_Phase_Properties is
new Generic_Internal_Discrete_Property (Gdk_Frame_Clock_Phase);
type Property_Gdk_Frame_Clock_Phase is new Gdk_Frame_Clock_Phase_Properties.Property;
------------------
-- Constructors --
------------------
function Get_Type return Glib.GType;
pragma Import (C, Get_Type, "gdk_frame_clock_get_type");
-------------
-- Methods --
-------------
procedure Begin_Updating (Self : not null access Gdk_Frame_Clock_Record);
-- Starts updates for an animation. Until a matching call to
-- Gdk.Frame_Clock.End_Updating is made, the frame clock will continually
-- request a new frame with the
-- Gdk.Frame_Clock.Gdk_Frame_Clock_Phase_Update phase. This function may be
-- called multiple times and frames will be requested until
-- Gdk.Frame_Clock.End_Updating is called the same number of times.
-- Since: gtk+ 3.8
procedure End_Updating (Self : not null access Gdk_Frame_Clock_Record);
-- Stops updates for an animation. See the documentation for
-- Gdk.Frame_Clock.Begin_Updating.
-- Since: gtk+ 3.8
function Get_Current_Timings
(Self : not null access Gdk_Frame_Clock_Record)
return Gdk.Frame_Timings.Gdk_Frame_Timings;
-- Gets the frame timings for the current frame.
-- Since: gtk+ 3.8
function Get_Frame_Counter
(Self : not null access Gdk_Frame_Clock_Record) return Gint64;
-- A Gdk.Frame_Clock.Gdk_Frame_Clock maintains a 64-bit counter that
-- increments for each frame drawn.
-- Since: gtk+ 3.8
function Get_Frame_Time
(Self : not null access Gdk_Frame_Clock_Record) return Gint64;
-- Gets the time that should currently be used for animations. Inside the
-- processing of a frame, it's the time used to compute the animation
-- position of everything in a frame. Outside of a frame, it's the time of
-- the conceptual "previous frame," which may be either the actual previous
-- frame time, or if that's too old, an updated time.
-- Since: gtk+ 3.8
function Get_History_Start
(Self : not null access Gdk_Frame_Clock_Record) return Gint64;
-- Gdk.Frame_Clock.Gdk_Frame_Clock internally keeps a history of
-- Gdk_Frame_Timing objects for recent frames that can be retrieved with
-- Gdk.Frame_Clock.Get_Timings. The set of stored frames is the set from
-- the counter values given by Gdk.Frame_Clock.Get_History_Start and
-- Gdk.Frame_Clock.Get_Frame_Counter, inclusive.
-- Since: gtk+ 3.8
procedure Get_Refresh_Info
(Self : not null access Gdk_Frame_Clock_Record;
Base_Time : Gint64;
Refresh_Interval_Return : in out Gint64;
Presentation_Time_Return : in out Gint64);
-- Using the frame history stored in the frame clock, finds the last known
-- presentation time and refresh interval, and assuming that presentation
-- times are separated by the refresh interval, predicts a presentation
-- time that is a multiple of the refresh interval after the last
-- presentation time, and later than Base_Time.
-- Since: gtk+ 3.8
-- "base_time": base time for determining a presentaton time
-- "refresh_interval_return": a location to store the determined refresh
-- interval, or null. A default refresh interval of 1/60th of a second will
-- be stored if no history is present.
-- "presentation_time_return": a location to store the next candidate
-- presentation time after the given base time. 0 will be will be stored if
-- no history is present.
function Get_Timings
(Self : not null access Gdk_Frame_Clock_Record;
Frame_Counter : Gint64) return Gdk.Frame_Timings.Gdk_Frame_Timings;
-- Retrieves a Gdk.Frame_Timings.Gdk_Frame_Timings object holding timing
-- information for the current frame or a recent frame. The
-- Gdk.Frame_Timings.Gdk_Frame_Timings object may not yet be complete: see
-- Gdk.Frame_Timings.Get_Complete.
-- Since: gtk+ 3.8
-- "frame_counter": the frame counter value identifying the frame to be
-- received.
procedure Request_Phase
(Self : not null access Gdk_Frame_Clock_Record;
Phase : Gdk_Frame_Clock_Phase);
-- Asks the frame clock to run a particular phase. The signal
-- corresponding the requested phase will be emitted the next time the
-- frame clock processes. Multiple calls to Gdk.Frame_Clock.Request_Phase
-- will be combined together and only one frame processed. If you are
-- displaying animated content and want to continually request the
-- Gdk.Frame_Clock.Gdk_Frame_Clock_Phase_Update phase for a period of time,
-- you should use Gdk.Frame_Clock.Begin_Updating instead, since this allows
-- GTK+ to adjust system parameters to get maximally smooth animations.
-- Since: gtk+ 3.8
-- "phase": the phase that is requested
-------------
-- Signals --
-------------
type Cb_Gdk_Frame_Clock_Void is not null access procedure
(Self : access Gdk_Frame_Clock_Record'Class);
type Cb_GObject_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class);
Signal_After_Paint : constant Glib.Signal_Name := "after-paint";
procedure On_After_Paint
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_Gdk_Frame_Clock_Void;
After : Boolean := False);
procedure On_After_Paint
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- This signal ends processing of the frame. Applications should generally
-- not handle this signal.
Signal_Before_Paint : constant Glib.Signal_Name := "before-paint";
procedure On_Before_Paint
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_Gdk_Frame_Clock_Void;
After : Boolean := False);
procedure On_Before_Paint
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- This signal begins processing of the frame. Applications should
-- generally not handle this signal.
Signal_Flush_Events : constant Glib.Signal_Name := "flush-events";
procedure On_Flush_Events
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_Gdk_Frame_Clock_Void;
After : Boolean := False);
procedure On_Flush_Events
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- This signal is used to flush pending motion events that are being
-- batched up and compressed together. Applications should not handle this
-- signal.
Signal_Layout : constant Glib.Signal_Name := "layout";
procedure On_Layout
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_Gdk_Frame_Clock_Void;
After : Boolean := False);
procedure On_Layout
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- This signal is emitted as the second step of toolkit and application
-- processing of the frame. Any work to update sizes and positions of
-- application elements should be performed. GTK+ normally handles this
-- internally.
Signal_Paint : constant Glib.Signal_Name := "paint";
procedure On_Paint
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_Gdk_Frame_Clock_Void;
After : Boolean := False);
procedure On_Paint
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- This signal is emitted as the third step of toolkit and application
-- processing of the frame. The frame is repainted. GDK normally handles
-- this internally and produces expose events, which are turned into GTK+
-- Gtk.Widget.Gtk_Widget::draw signals.
Signal_Resume_Events : constant Glib.Signal_Name := "resume-events";
procedure On_Resume_Events
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_Gdk_Frame_Clock_Void;
After : Boolean := False);
procedure On_Resume_Events
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- This signal is emitted after processing of the frame is finished, and
-- is handled internally by GTK+ to resume normal event processing.
-- Applications should not handle this signal.
Signal_Update : constant Glib.Signal_Name := "update";
procedure On_Update
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_Gdk_Frame_Clock_Void;
After : Boolean := False);
procedure On_Update
(Self : not null access Gdk_Frame_Clock_Record;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False);
-- This signal is emitted as the first step of toolkit and application
-- processing of the frame. Animations should be updated using
-- Gdk.Frame_Clock.Get_Frame_Time. Applications can connect directly to
-- this signal, or use Gtk.Widget.Add_Tick_Callback as a more convenient
-- interface.
end Gdk.Frame_Clock;