FrameClockProtocol

public protocol FrameClockProtocol : ObjectProtocol

The FrameClockProtocol protocol exposes the methods and properties of an underlying GdkFrameClock instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see FrameClock. Alternatively, use FrameClockRef as a lighweight, unowned reference if you already have an instance you just want to use.

A GdkFrameClock tells the application when to update and repaint a surface.

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.

GdkFrameClock 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 [methodGdk.FrameClock.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 GdkFrameClock class for documentation of the phases. GDK_FRAME_CLOCK_PHASE_UPDATE and the [signalGdkFrameClock::update] signal are most interesting for application writers, and are used to update the animations, using the frame time given by [metohdGdk.FrameClock.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 [methodGdk.FrameClock.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 [methodGdk.FrameClock.get_frame_time] and the value inside the [signalGdkFrameClock::update] signal of the clock, they will stay exactly synchronized.

Show on GitHub
  • ptr

    Untyped pointer to the underlying GdkFrameClock instance.

    Declaration

    Swift

    var ptr: UnsafeMutableRawPointer! { get }
    Show on GitHub
  • frame_clock_ptr Default implementation

    Typed pointer to the underlying GdkFrameClock instance.

    Default Implementation

    Return the stored, untyped pointer as a typed pointer to the GdkFrameClock instance.

    Declaration

    Swift

    var frame_clock_ptr: UnsafeMutablePointer<GdkFrameClock>! { get }
    Show on GitHub

  • Required Initialiser for types conforming to FrameClockProtocol

    Declaration

    Swift

    init(raw: UnsafeMutableRawPointer)
    Show on GitHub

FrameClock signals

  • Connect a Swift signal handler to the given, typed FrameClockSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: FrameClockSignalName, flags f: ConnectFlags = ConnectFlags(0), handler h: @escaping SignalHandler) -> Int

    Parameters

    signal

    The signal to connect
    flags

    The connection flags to use
    data

    A pointer to user data to provide to the callback
    destroyData

    A GClosureNotify C function to destroy the data pointed to by userData
    handler

    The Swift signal handler (function or callback) to invoke on the given signal

    Return Value

    The signal handler ID (always greater than 0 for successful connections)

    Show on GitHub

  • Connect a C signal handler to the given, typed FrameClockSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: FrameClockSignalName, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer!, destroyData destructor: GClosureNotify? = nil, signalHandler h: @escaping GCallback) -> Int

    Parameters

    signal

    The signal to connect
    flags

    The connection flags to use
    data

    A pointer to user data to provide to the callback
    destroyData

    A GClosureNotify C function to destroy the data pointed to by userData
    signalHandler

    The C function to be called on the given signal

    Return Value

    The signal handler ID (always greater than 0 for successful connections)

    Show on GitHub
  • onAfterPaint(flags:handler:) Extension method

    This signal ends processing of the frame.

    Applications should generally not handle this signal.

    Note

    This represents the underlying after-paint signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onAfterPaint(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: FrameClockRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the afterPaint signal is emitted
    Show on GitHub
  • afterPaintSignal Extension method

    Typed after-paint signal for using the connect(signal:) methods

    Declaration

    Swift

    static var afterPaintSignal: FrameClockSignalName { get }
    Show on GitHub

  • Begins processing of the frame.

    Applications should generally not handle this signal.

    Note

    This represents the underlying before-paint signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onBeforePaint(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: FrameClockRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the beforePaint signal is emitted
    Show on GitHub
  • beforePaintSignal Extension method

    Typed before-paint signal for using the connect(signal:) methods

    Declaration

    Swift

    static var beforePaintSignal: FrameClockSignalName { get }
    Show on GitHub

  • Used to flush pending motion events that are being batched up and compressed together.

    Applications should not handle this signal.

    Note

    This represents the underlying flush-events signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onFlushEvents(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: FrameClockRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the flushEvents signal is emitted
    Show on GitHub
  • flushEventsSignal Extension method

    Typed flush-events signal for using the connect(signal:) methods

    Declaration

    Swift

    static var flushEventsSignal: FrameClockSignalName { get }
    Show on GitHub
  • onLayout(flags:handler:) Extension method

    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.

    Note

    This represents the underlying layout signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onLayout(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: FrameClockRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the layout signal is emitted
    Show on GitHub
  • layoutSignal Extension method

    Typed layout signal for using the connect(signal:) methods

    Declaration

    Swift

    static var layoutSignal: FrameClockSignalName { get }
    Show on GitHub
  • onPaint(flags:handler:) Extension method

    Emitted as the third step of toolkit and application processing of the frame.

    The frame is repainted. GDK normally handles this internally and emits [signalGdk.Surface::render] signals which are turned into [signalGtk.Widget::snapshot] signals by GTK.

    Note

    This represents the underlying paint signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onPaint(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: FrameClockRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the paint signal is emitted
    Show on GitHub
  • paintSignal Extension method

    Typed paint signal for using the connect(signal:) methods

    Declaration

    Swift

    static var paintSignal: FrameClockSignalName { get }
    Show on GitHub

  • Emitted after processing of the frame is finished.

    This signal is handled internally by GTK to resume normal event processing. Applications should not handle this signal.

    Note

    This represents the underlying resume-events signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onResumeEvents(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: FrameClockRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the resumeEvents signal is emitted
    Show on GitHub
  • resumeEventsSignal Extension method

    Typed resume-events signal for using the connect(signal:) methods

    Declaration

    Swift

    static var resumeEventsSignal: FrameClockSignalName { get }
    Show on GitHub
  • onUpdate(flags:handler:) Extension method

    Emitted as the first step of toolkit and application processing of the frame.

    Animations should be updated using [methodGdk.FrameClock.get_frame_time]. Applications can connect directly to this signal, or use [methodGtk.Widget.add_tick_callback] as a more convenient interface.

    Note

    This represents the underlying update signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onUpdate(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: FrameClockRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the update signal is emitted
    Show on GitHub
  • updateSignal Extension method

    Typed update signal for using the connect(signal:) methods

    Declaration

    Swift

    static var updateSignal: FrameClockSignalName { get }
    Show on GitHub

FrameClock Class: FrameClockProtocol extension (methods and fields)

  • beginUpdating() Extension method

    Starts updates for an animation.

    Until a matching call to [methodGdk.FrameClock.end_updating] is made, the frame clock will continually request a new frame with the 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.

    Declaration

    Swift

    @inlinable
func beginUpdating()
    Show on GitHub
  • endUpdating() Extension method

    Stops updates for an animation.

    See the documentation for [methodGdk.FrameClock.begin_updating].

    Declaration

    Swift

    @inlinable
func endUpdating()
    Show on GitHub
  • getCurrentTimings() Extension method

    Gets the frame timings for the current frame.

    Declaration

    Swift

    @inlinable
func getCurrentTimings() -> FrameTimingsRef!
    Show on GitHub
  • getFps() Extension method

    Calculates the current frames-per-second, based on the frame timings of frame_clock.

    Declaration

    Swift

    @inlinable
func getFps() -> CDouble
    Show on GitHub
  • getFrameCounter() Extension method

    GdkFrameClock maintains a 64-bit counter that increments for each frame drawn.

    Declaration

    Swift

    @inlinable
func getFrameCounter() -> gint64
    Show on GitHub
  • getFrameTime() Extension method

    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.

    Declaration

    Swift

    @inlinable
func getFrameTime() -> gint64
    Show on GitHub
  • getHistoryStart() Extension method

    Returns the frame counter for the oldest frame available in history.

    GdkFrameClock internally keeps a history of GdkFrameTimings objects for recent frames that can be retrieved with [methodGdk.FrameClock.get_timings]. The set of stored frames is the set from the counter values given by [methodGdk.FrameClock.get_history_start] and [methodGdk.FrameClock.get_frame_counter], inclusive.

    Declaration

    Swift

    @inlinable
func getHistoryStart() -> gint64
    Show on GitHub

  • Predicts a presentation time, based on history.

    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.

    Declaration

    Swift

    @inlinable
func getRefreshInfo(baseTime: gint64, refreshIntervalReturn: UnsafeMutablePointer<gint64>! = nil, presentationTimeReturn: UnsafeMutablePointer<gint64>!)
    Show on GitHub
  • getTimings(frameCounter:) Extension method

    Retrieves a GdkFrameTimings object holding timing information for the current frame or a recent frame.

    The GdkFrameTimings object may not yet be complete: see [methodGdk.FrameTimings.get_complete].

    Declaration

    Swift

    @inlinable
func getTimings(frameCounter: gint64) -> FrameTimingsRef!
    Show on GitHub
  • request(phase:) Extension method

    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_PHASE_UPDATE phase for a period of time, you should use [methodGdk.FrameClock.begin_updating] instead, since this allows GTK to adjust system parameters to get maximally smooth animations.

    Declaration

    Swift

    @inlinable
func request(phase: FrameClockPhase)
    Show on GitHub
  • currentTimings Extension method

    Gets the frame timings for the current frame.

    Declaration

    Swift

    @inlinable
var currentTimings: FrameTimingsRef! { get }
    Show on GitHub
  • fps Extension method

    Calculates the current frames-per-second, based on the frame timings of frame_clock.

    Declaration

    Swift

    @inlinable
var fps: CDouble { get }
    Show on GitHub
  • frameCounter Extension method

    GdkFrameClock maintains a 64-bit counter that increments for each frame drawn.

    Declaration

    Swift

    @inlinable
var frameCounter: gint64 { get }
    Show on GitHub
  • frameTime Extension method

    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.

    Declaration

    Swift

    @inlinable
var frameTime: gint64 { get }
    Show on GitHub
  • historyStart Extension method

    Returns the frame counter for the oldest frame available in history.

    GdkFrameClock internally keeps a history of GdkFrameTimings objects for recent frames that can be retrieved with [methodGdk.FrameClock.get_timings]. The set of stored frames is the set from the counter values given by [methodGdk.FrameClock.get_history_start] and [methodGdk.FrameClock.get_frame_counter], inclusive.

    Declaration

    Swift

    @inlinable
var historyStart: gint64 { get }
    Show on GitHub