scheduleForcedFrame method

void scheduleForcedFrame ()

Schedules a new frame by calling Window.scheduleFrame.

After this is called, the engine will call handleBeginFrame, even if frames would normally not be scheduled by scheduleFrame (e.g. even if the device's screen is turned off).

The framework uses this to force a frame to be rendered at the correct size when the phone is rotated, so that a correctly-sized rendering is available when the screen is turned back on.

To have a stack trace printed to the console any time this function schedules a frame, set debugPrintScheduleFrameStacks to true.

Prefer using scheduleFrame unless it is imperative that a frame be scheduled immediately, since using scheduleForceFrame will cause significantly higher battery usage when the device should be idle.

Consider using scheduleWarmUpFrame instead if the goal is to update the rendering as soon as possible (e.g. at application startup).

Implementation

void scheduleForcedFrame() {
  if (_hasScheduledFrame)
    return;
  assert(() {
    if (debugPrintScheduleFrameStacks)
      debugPrintStack(label: 'scheduleForcedFrame() called. Current phase is $schedulerPhase.');
    return true;
  }());
  window.scheduleFrame();
  _hasScheduledFrame = true;
}