1. ------------------------------------------------------------------------------ 
  2. --                                                                          -- 
  3. --      Copyright (C) 1998-2000 E. Briot, J. Brobecker and A. Charlet       -- 
  4. --                     Copyright (C) 2000-2014, AdaCore                     -- 
  5. --                                                                          -- 
  6. -- This library is free software;  you can redistribute it and/or modify it -- 
  7. -- under terms of the  GNU General Public License  as published by the Free -- 
  8. -- Software  Foundation;  either version 3,  or (at your  option) any later -- 
  9. -- version. This library is distributed in the hope that it will be useful, -- 
  10. -- but WITHOUT ANY WARRANTY;  without even the implied warranty of MERCHAN- -- 
  11. -- TABILITY or FITNESS FOR A PARTICULAR PURPOSE.                            -- 
  12. --                                                                          -- 
  13. -- As a special exception under Section 7 of GPL version 3, you are granted -- 
  14. -- additional permissions described in the GCC Runtime Library Exception,   -- 
  15. -- version 3.1, as published by the Free Software Foundation.               -- 
  16. --                                                                          -- 
  17. -- You should have received a copy of the GNU General Public License and    -- 
  18. -- a copy of the GCC Runtime Library Exception along with this program;     -- 
  19. -- see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    -- 
  20. -- <http://www.gnu.org/licenses/>.                                          -- 
  21. --                                                                          -- 
  22. ------------------------------------------------------------------------------ 
  23.  
  24. --  <description> 
  25. --  A Gdk.Frame_Clock.Gdk_Frame_Clock tells the application when to update and 
  26. --  repaint a window. This may be synced to the vertical refresh rate of the 
  27. --  monitor, for example. Even when the frame clock uses a simple timer rather 
  28. --  than a hardware-based vertical sync, the frame clock helps because it 
  29. --  ensures everything paints at the same time (reducing the total number of 
  30. --  frames). The frame clock can also automatically stop painting when it knows 
  31. --  the frames will not be visible, or scale back animation framerates. 
  32. -- 
  33. --  Gdk.Frame_Clock.Gdk_Frame_Clock is designed to be compatible with an 
  34. --  OpenGL-based implementation or with mozRequestAnimationFrame in Firefox, 
  35. --  for example. 
  36. -- 
  37. --  A frame clock is idle until someone requests a frame with 
  38. --  Gdk.Frame_Clock.Request_Phase. At some later point that makes sense for the 
  39. --  synchronization being implemented, the clock will process a frame and emit 
  40. --  signals for each phase that has been requested. (See the signals of the 
  41. --  Gdk.Frame_Clock.Gdk_Frame_Clock class for documentation of the phases. 
  42. --  Gdk.Frame_Clock.Gdk_Frame_Clock_Phase_Update and the 
  43. --  Gdk.Frame_Clock.Gdk_Frame_Clock::update signal are most interesting for 
  44. --  application writers, and are used to update the animations, using the frame 
  45. --  time given by Gdk.Frame_Clock.Get_Frame_Time. 
  46. -- 
  47. --  The frame time is reported in microseconds and generally in the same 
  48. --  timescale as g_get_monotonic_time, however, it is not the same as 
  49. --  g_get_monotonic_time. The frame time does not advance during the time a 
  50. --  frame is being painted, and outside of a frame, an attempt is made so that 
  51. --  all calls to Gdk.Frame_Clock.Get_Frame_Time that are called at a "similar" 
  52. --  time get the same value. This means that if different animations are timed 
  53. --  by looking at the difference in time between an initial value from 
  54. --  Gdk.Frame_Clock.Get_Frame_Time and the value inside the 
  55. --  Gdk.Frame_Clock.Gdk_Frame_Clock::update signal of the clock, they will stay 
  56. --  exactly synchronized. 
  57. -- 
  58. --  </description> 
  59. pragma Ada_2005; 
  60.  
  61. pragma Warnings (Off, "*is already use-visible*"); 
  62. with Gdk.Frame_Timings;       use Gdk.Frame_Timings; 
  63. with Glib;                    use Glib; 
  64. with Glib.Generic_Properties; use Glib.Generic_Properties; 
  65. with Glib.Object;             use Glib.Object; 
  66.  
  67. package Gdk.Frame_Clock is 
  68.  
  69.    type Gdk_Frame_Clock_Record is new GObject_Record with null record; 
  70.    type Gdk_Frame_Clock is access all Gdk_Frame_Clock_Record'Class; 
  71.  
  72.    type Gdk_Frame_Clock_Phase is mod 2 ** Integer'Size; 
  73.    pragma Convention (C, Gdk_Frame_Clock_Phase); 
  74.    --  Gdk.Frame_Clock.Gdk_Frame_Clock_Phase is used to represent the 
  75.    --  different paint clock phases that can be requested. The elements of the 
  76.    --  enumeration correspond to the signals of Gdk_Paint_Clock. 
  77.  
  78.    Gdk_Frame_Clock_Phase_None : constant Gdk_Frame_Clock_Phase := 0; 
  79.    Gdk_Frame_Clock_Phase_Flush_Events : constant Gdk_Frame_Clock_Phase := 1; 
  80.    Gdk_Frame_Clock_Phase_Before_Paint : constant Gdk_Frame_Clock_Phase := 2; 
  81.    Gdk_Frame_Clock_Phase_Update : constant Gdk_Frame_Clock_Phase := 4; 
  82.    Gdk_Frame_Clock_Phase_Layout : constant Gdk_Frame_Clock_Phase := 8; 
  83.    Gdk_Frame_Clock_Phase_Paint : constant Gdk_Frame_Clock_Phase := 16; 
  84.    Gdk_Frame_Clock_Phase_Resume_Events : constant Gdk_Frame_Clock_Phase := 32; 
  85.    Gdk_Frame_Clock_Phase_After_Paint : constant Gdk_Frame_Clock_Phase := 64; 
  86.  
  87.    ---------------------------- 
  88.    -- Enumeration Properties -- 
  89.    ---------------------------- 
  90.  
  91.    package Gdk_Frame_Clock_Phase_Properties is 
  92.       new Generic_Internal_Discrete_Property (Gdk_Frame_Clock_Phase); 
  93.    type Property_Gdk_Frame_Clock_Phase is new Gdk_Frame_Clock_Phase_Properties.Property; 
  94.  
  95.    ------------------ 
  96.    -- Constructors -- 
  97.    ------------------ 
  98.  
  99.    function Get_Type return Glib.GType; 
  100.    pragma Import (C, Get_Type, "gdk_frame_clock_get_type"); 
  101.  
  102.    ------------- 
  103.    -- Methods -- 
  104.    ------------- 
  105.  
  106.    procedure Begin_Updating (Self : not null access Gdk_Frame_Clock_Record); 
  107.    --  Starts updates for an animation. Until a matching call to 
  108.    --  Gdk.Frame_Clock.End_Updating is made, the frame clock will continually 
  109.    --  request a new frame with the 
  110.    --  Gdk.Frame_Clock.Gdk_Frame_Clock_Phase_Update phase. This function may be 
  111.    --  called multiple times and frames will be requested until 
  112.    --  Gdk.Frame_Clock.End_Updating is called the same number of times. 
  113.    --  Since: gtk+ 3.8 
  114.  
  115.    procedure End_Updating (Self : not null access Gdk_Frame_Clock_Record); 
  116.    --  Stops updates for an animation. See the documentation for 
  117.    --  Gdk.Frame_Clock.Begin_Updating. 
  118.    --  Since: gtk+ 3.8 
  119.  
  120.    function Get_Current_Timings 
  121.       (Self : not null access Gdk_Frame_Clock_Record) 
  122.        return Gdk.Frame_Timings.Gdk_Frame_Timings; 
  123.    --  Gets the frame timings for the current frame. 
  124.    --  Since: gtk+ 3.8 
  125.  
  126.    function Get_Frame_Counter 
  127.       (Self : not null access Gdk_Frame_Clock_Record) return Gint64; 
  128.    --  A Gdk.Frame_Clock.Gdk_Frame_Clock maintains a 64-bit counter that 
  129.    --  increments for each frame drawn. 
  130.    --  Since: gtk+ 3.8 
  131.  
  132.    function Get_Frame_Time 
  133.       (Self : not null access Gdk_Frame_Clock_Record) return Gint64; 
  134.    --  Gets the time that should currently be used for animations. Inside the 
  135.    --  processing of a frame, it's the time used to compute the animation 
  136.    --  position of everything in a frame. Outside of a frame, it's the time of 
  137.    --  the conceptual "previous frame," which may be either the actual previous 
  138.    --  frame time, or if that's too old, an updated time. 
  139.    --  Since: gtk+ 3.8 
  140.  
  141.    function Get_History_Start 
  142.       (Self : not null access Gdk_Frame_Clock_Record) return Gint64; 
  143.    --  Gdk.Frame_Clock.Gdk_Frame_Clock internally keeps a history of 
  144.    --  Gdk_Frame_Timing objects for recent frames that can be retrieved with 
  145.    --  Gdk.Frame_Clock.Get_Timings. The set of stored frames is the set from 
  146.    --  the counter values given by Gdk.Frame_Clock.Get_History_Start and 
  147.    --  Gdk.Frame_Clock.Get_Frame_Counter, inclusive. 
  148.    --  Since: gtk+ 3.8 
  149.  
  150.    procedure Get_Refresh_Info 
  151.       (Self                     : not null access Gdk_Frame_Clock_Record; 
  152.        Base_Time                : Gint64; 
  153.        Refresh_Interval_Return  : in out Gint64; 
  154.        Presentation_Time_Return : in out Gint64); 
  155.    --  Using the frame history stored in the frame clock, finds the last known 
  156.    --  presentation time and refresh interval, and assuming that presentation 
  157.    --  times are separated by the refresh interval, predicts a presentation 
  158.    --  time that is a multiple of the refresh interval after the last 
  159.    --  presentation time, and later than Base_Time. 
  160.    --  Since: gtk+ 3.8 
  161.    --  "base_time": base time for determining a presentaton time 
  162.    --  "refresh_interval_return": a location to store the determined refresh 
  163.    --  interval, or null. A default refresh interval of 1/60th of a second will 
  164.    --  be stored if no history is present. 
  165.    --  "presentation_time_return": a location to store the next candidate 
  166.    --  presentation time after the given base time. 0 will be will be stored if 
  167.    --  no history is present. 
  168.  
  169.    function Get_Timings 
  170.       (Self          : not null access Gdk_Frame_Clock_Record; 
  171.        Frame_Counter : Gint64) return Gdk.Frame_Timings.Gdk_Frame_Timings; 
  172.    --  Retrieves a Gdk.Frame_Timings.Gdk_Frame_Timings object holding timing 
  173.    --  information for the current frame or a recent frame. The 
  174.    --  Gdk.Frame_Timings.Gdk_Frame_Timings object may not yet be complete: see 
  175.    --  Gdk.Frame_Timings.Get_Complete. 
  176.    --  Since: gtk+ 3.8 
  177.    --  "frame_counter": the frame counter value identifying the frame to be 
  178.    --  received. 
  179.  
  180.    procedure Request_Phase 
  181.       (Self  : not null access Gdk_Frame_Clock_Record; 
  182.        Phase : Gdk_Frame_Clock_Phase); 
  183.    --  Asks the frame clock to run a particular phase. The signal 
  184.    --  corresponding the requested phase will be emitted the next time the 
  185.    --  frame clock processes. Multiple calls to Gdk.Frame_Clock.Request_Phase 
  186.    --  will be combined together and only one frame processed. If you are 
  187.    --  displaying animated content and want to continually request the 
  188.    --  Gdk.Frame_Clock.Gdk_Frame_Clock_Phase_Update phase for a period of time, 
  189.    --  you should use Gdk.Frame_Clock.Begin_Updating instead, since this allows 
  190.    --  GTK+ to adjust system parameters to get maximally smooth animations. 
  191.    --  Since: gtk+ 3.8 
  192.    --  "phase": the phase that is requested 
  193.  
  194.    ------------- 
  195.    -- Signals -- 
  196.    ------------- 
  197.  
  198.    type Cb_Gdk_Frame_Clock_Void is not null access procedure 
  199.      (Self : access Gdk_Frame_Clock_Record'Class); 
  200.  
  201.    type Cb_GObject_Void is not null access procedure 
  202.      (Self : access Glib.Object.GObject_Record'Class); 
  203.  
  204.    Signal_After_Paint : constant Glib.Signal_Name := "after-paint"; 
  205.    procedure On_After_Paint 
  206.       (Self  : not null access Gdk_Frame_Clock_Record; 
  207.        Call  : Cb_Gdk_Frame_Clock_Void; 
  208.        After : Boolean := False); 
  209.    procedure On_After_Paint 
  210.       (Self  : not null access Gdk_Frame_Clock_Record; 
  211.        Call  : Cb_GObject_Void; 
  212.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  213.        After : Boolean := False); 
  214.    --  This signal ends processing of the frame. Applications should generally 
  215.    --  not handle this signal. 
  216.  
  217.    Signal_Before_Paint : constant Glib.Signal_Name := "before-paint"; 
  218.    procedure On_Before_Paint 
  219.       (Self  : not null access Gdk_Frame_Clock_Record; 
  220.        Call  : Cb_Gdk_Frame_Clock_Void; 
  221.        After : Boolean := False); 
  222.    procedure On_Before_Paint 
  223.       (Self  : not null access Gdk_Frame_Clock_Record; 
  224.        Call  : Cb_GObject_Void; 
  225.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  226.        After : Boolean := False); 
  227.    --  This signal begins processing of the frame. Applications should 
  228.    --  generally not handle this signal. 
  229.  
  230.    Signal_Flush_Events : constant Glib.Signal_Name := "flush-events"; 
  231.    procedure On_Flush_Events 
  232.       (Self  : not null access Gdk_Frame_Clock_Record; 
  233.        Call  : Cb_Gdk_Frame_Clock_Void; 
  234.        After : Boolean := False); 
  235.    procedure On_Flush_Events 
  236.       (Self  : not null access Gdk_Frame_Clock_Record; 
  237.        Call  : Cb_GObject_Void; 
  238.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  239.        After : Boolean := False); 
  240.    --  This signal is used to flush pending motion events that are being 
  241.    --  batched up and compressed together. Applications should not handle this 
  242.    --  signal. 
  243.  
  244.    Signal_Layout : constant Glib.Signal_Name := "layout"; 
  245.    procedure On_Layout 
  246.       (Self  : not null access Gdk_Frame_Clock_Record; 
  247.        Call  : Cb_Gdk_Frame_Clock_Void; 
  248.        After : Boolean := False); 
  249.    procedure On_Layout 
  250.       (Self  : not null access Gdk_Frame_Clock_Record; 
  251.        Call  : Cb_GObject_Void; 
  252.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  253.        After : Boolean := False); 
  254.    --  This signal is emitted as the second step of toolkit and application 
  255.    --  processing of the frame. Any work to update sizes and positions of 
  256.    --  application elements should be performed. GTK+ normally handles this 
  257.    --  internally. 
  258.  
  259.    Signal_Paint : constant Glib.Signal_Name := "paint"; 
  260.    procedure On_Paint 
  261.       (Self  : not null access Gdk_Frame_Clock_Record; 
  262.        Call  : Cb_Gdk_Frame_Clock_Void; 
  263.        After : Boolean := False); 
  264.    procedure On_Paint 
  265.       (Self  : not null access Gdk_Frame_Clock_Record; 
  266.        Call  : Cb_GObject_Void; 
  267.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  268.        After : Boolean := False); 
  269.    --  This signal is emitted as the third step of toolkit and application 
  270.    --  processing of the frame. The frame is repainted. GDK normally handles 
  271.    --  this internally and produces expose events, which are turned into GTK+ 
  272.    --  Gtk.Widget.Gtk_Widget::draw signals. 
  273.  
  274.    Signal_Resume_Events : constant Glib.Signal_Name := "resume-events"; 
  275.    procedure On_Resume_Events 
  276.       (Self  : not null access Gdk_Frame_Clock_Record; 
  277.        Call  : Cb_Gdk_Frame_Clock_Void; 
  278.        After : Boolean := False); 
  279.    procedure On_Resume_Events 
  280.       (Self  : not null access Gdk_Frame_Clock_Record; 
  281.        Call  : Cb_GObject_Void; 
  282.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  283.        After : Boolean := False); 
  284.    --  This signal is emitted after processing of the frame is finished, and 
  285.    --  is handled internally by GTK+ to resume normal event processing. 
  286.    --  Applications should not handle this signal. 
  287.  
  288.    Signal_Update : constant Glib.Signal_Name := "update"; 
  289.    procedure On_Update 
  290.       (Self  : not null access Gdk_Frame_Clock_Record; 
  291.        Call  : Cb_Gdk_Frame_Clock_Void; 
  292.        After : Boolean := False); 
  293.    procedure On_Update 
  294.       (Self  : not null access Gdk_Frame_Clock_Record; 
  295.        Call  : Cb_GObject_Void; 
  296.        Slot  : not null access Glib.Object.GObject_Record'Class; 
  297.        After : Boolean := False); 
  298.    --  This signal is emitted as the first step of toolkit and application 
  299.    --  processing of the frame. Animations should be updated using 
  300.    --  Gdk.Frame_Clock.Get_Frame_Time. Applications can connect directly to 
  301.    --  this signal, or use Gtk.Widget.Add_Tick_Callback as a more convenient 
  302.    --  interface. 
  303.  
  304. end Gdk.Frame_Clock;