// crtc_msc：CRTC当前的msc，即framebuffer刷新的次数
// ust：CRTC当前的msc开始的事件，单位为ns，有的硬件ust为32位，present将其转成64位
static void present_execute(present_vblank_ptr vblank, uint64_t ust, uint64_t crtc_msc){
    WindowPtr                   window = vblank->window;
    ScreenPtr                   screen = window->drawable.pScreen;
    // 窗口所在屏幕
    present_screen_priv_ptr     screen_priv = present_screen_priv(screen);
    if (vblank && vblank->crtc) {
        // CRTC对应屏幕，当窗口从一个显示器切换至另一个显示器时，这两个屏幕不同
        screen_priv=present_screen_priv(vblank->crtc->pScreen);
    }
    // 若vblank的target_msc为crtc_msc+1，则调用queue_vblank注册vblank，结束处理
    if (present_execute_wait(vblank, crtc_msc))
        return;
    if (vblank->flip && vblank->pixmap && vblank->window) {
        // vblank需要翻页，但当前有窗口正在翻页或者取消翻页，则该vblank挂起，最终会删除该操作
        if (screen_priv->flip_pending || screen_priv->unflip_event_id) {
            xorg_list_del(&vblank->event_queue);
            xorg_list_append(&vblank->event_queue, &present_flip_queue);
            vblank->flip_ready = TRUE;
            return;
        }
    }
    将vblank从present_exec_queue或者present_flip_queue列表中删除
    xorg_list_del(&vblank->event_queue);
    将vblank从其对应窗口的vblank列表中删除
    xorg_list_del(&vblank->window_list);
    vblank->queued = FALSE;
    // 正常操作，需要翻页或赋值
    if (vblank->pixmap && vblank->window &&
        (vblank->reason < PRESENT_FLIP_REASON_DRIVER_TEARFREE ||
        // TearFree导致的暂时不能使用硬件翻页的情况，在将来某个时间可能可以
         vblank->exec_msc != vblank->target_msc)) {
        if (vblank->flip) {
            // 缓冲正翻页的vblank，并加入present_flip_queue列表中
            screen_priv->flip_pending = vblank;
            xorg_list_add(&vblank->event_queue, &present_flip_queue);
            // 发起翻页命令，如：drmModePageFlip
            if (present_flip(vblank->crtc, vblank->event_id, vblank->target_msc, vblank->pixmap, vblank->sync_flip)) {
                RegionPtr damage;
                // 与已翻页的窗口不同（窗口切换了），将已翻页的窗口的pixmap更新为屏幕的pixmap
                // 注意：以下都是数据结构更新，而非显示更新
                if (screen_priv->flip_window && screen_priv->flip_window != window)
                    present_set_tree_pixmap(screen_priv->flip_window, screen_priv->flip_pixmap, (*screen->GetScreenPixmap)(screen));
                // 将窗口和屏幕根窗口的pixmap更新为待显示的pixmap
                present_set_tree_pixmap(vblank->window, NULL, vblank->pixmap);
                present_set_tree_pixmap(screen->root, NULL, vblank->pixmap);
                // Report update region as damaged
                if (vblank->update) {
                    damage = vblank->update;
                    RegionIntersect(damage, damage, &window->clipList);
                } else
                    damage = &window->clipList;
                DamageDamageRegion(&vblank->window->drawable, damage);
                return;
            }
            // 若是翻页操作失败，则将vblank从present_flip_queue列表中删除
            xorg_list_del(&vblank->event_queue);
            // 此时间无翻页请求，因此请空flip_pending
            screen_priv->flip_pending = NULL;
            vblank->flip = FALSE;
            // 硬件翻页时，更新了exec_msc，如：TearFree硬件翻页或者同步翻页
            vblank->exec_msc = vblank->target_msc;
        }
        if (screen_priv->flip_pending) {
            // vblank指定的窗口正在翻页中，则终止该窗口的翻页，将该窗口和根窗口的pixmap更新为屏幕pixmap
            if (window == screen_priv->flip_pending->window)
                present_set_abort_flip(screen);
        } else if (!screen_priv->unflip_event_id) {
            // 该窗口的内容已经翻页了，取消翻页，将该窗口和根窗口的pixmap更新为屏幕pixmap，更新为屏幕pixmap
            if (window == screen_priv->flip_window)
                present_unflip(screen); // 消翻页，更新为屏幕pixmap
        }
        // 将pixmap中的内容复制到窗口的pixmap中，更新窗口内容
        present_execute_copy(vblank, crtc_msc);
        // TareFree翻页，因CRTC正在进行翻页，导致该vblank无法硬件翻页
        if (!vblank->queued && vblank->reason >= PRESENT_FLIP_REASON_DRIVER_TEARFREE) {
            uint64_t completion_msc = crtc_msc + 1;
            // If TearFree is already flipping then the presentation will be visible at the *next* next vblank.
            // This calculation only matters or the vblank event fallback.
            if (vblank->reason == PRESENT_FLIP_REASON_DRIVER_TEARFREE_FLIPPING && vblank->exec_msc < crtc_msc)
                    completion_msc++;
            // Try the fake flip first and then fall back to a vblank event
            if (present_flip(vblank->crtc, vblank->event_id, 0, NULL, TRUE) ||
                Success == screen_priv->queue_vblank(screen, window, vblank->crtc,  vblank->event_id, completion_msc)) {
                // Ensure present_execute_post() runs at the next execution
                vblank->exec_msc = vblank->target_msc;
                vblank->queued = TRUE;
            }
        }
        if (vblank->queued) {
            xorg_list_add(&vblank->event_queue, &present_exec_queue);
            xorg_list_append(&vblank->window_list, &present_get_window_priv(window, TRUE)->vblank);
            return;
        }
    }
    // 发送PresentCompleteNofity事件
    present_execute_post(vblank, ust, crtc_msc);
}

void present_event_notify(uint64_t event_id, uint64_t ust, uint64_t msc){
    present_vblank_ptr  vblank;
    int                 s;
    if (!event_id)
        return;
    xorg_list_for_each_entry(vblank, &present_exec_queue, event_queue) {
        int64_t match = event_id - vblank->event_id;
        if (match == 0) { // vblank时间到，处理该事件传递vblank的窗口显示（翻页或拷贝）
            present_execute(vblank, ust, msc);
            return;
        }
    }
    xorg_list_for_each_entry(vblank, &present_flip_queue, event_queue) {
        if (vblank->event_id == event_id) {
            if (vblank->queued)
                // 可能是flipe_ready的vblank，执行翻页操作
                present_execute(vblank, ust, msc);
            else
                // 1. 为flip_window触发SyncFence，发送PresentIdleNofity事件
                // 2. 完成了翻页操作，更新flip_window为此窗口
                // 3. 为此窗口发送PresentCompleteNofity事件
                // 4. 调用重新执行因等待翻页而挂起的任务，（flip_ready=true）
                present_flip_notify(vblank, ust, msc);
            return;
        }
    }
    for (s = 0; s < screenInfo.numScreens; s++) {
        ScreenPtr               screen = screenInfo.screens[s];
        present_screen_priv_ptr screen_priv = present_screen_priv(screen);
        // 取消翻页，发送PresentIdleNotify事件通知
        if (event_id == screen_priv->unflip_event_id) {
            screen_priv->unflip_event_id = 0;
            present_flip_idle(screen);
            present_flip_try_ready(screen);
            return;
        }
    }
}

static Bool xwl_present_flip(present_vblank_ptr vblank, RegionPtr damage){
    WindowPtr present_window = vblank->window;
    PixmapPtr pixmap = vblank->pixmap;
    struct xwl_window           *xwl_window = xwl_window_from_window(present_window);
    struct xwl_present_window   *xwl_present_window = xwl_present_window_priv(present_window);
    BoxPtr                      damage_box;
    struct wl_buffer            *buffer;
    struct xwl_present_event    *event = xwl_present_event_from_vblank(vblank);

    if (!xwl_window)
        return FALSE;
    // 根据pixmap中的bo，使用zwp linux-dmabuf扩展协议创建与bo关联的wl_buffer
    buffer = xwl_glamor_pixmap_get_wl_buffer(pixmap);
    if (!buffer) {
        ErrorF("present: Error getting buffer\n");
        return FALSE;
    }
    // 修改区域
    damage_box = RegionExtents(damage);
    pixmap->refcnt++;
    event->pixmap = pixmap;
    // 注册wayland释放wl_buffer时的回调函数，触发回调时发送IdleNotify事件，pixmap可重用
    xwl_pixmap_set_buffer_release_cb(pixmap, xwl_present_buffer_release, event);
    // wl_buffer与窗口（surface）关联
    wl_surface_attach(xwl_window->surface, buffer, 0, 0);
    if (xorg_list_is_empty(&xwl_present_window->frame_callback_list)) {
        xorg_list_add(&xwl_present_window->frame_callback_list, &xwl_window->frame_callback_list);
    }
    // 未注册vblank信号处理函数，则调用wl_surface_frame注册
    if (!xwl_window->frame_callback)
        xwl_window_create_frame_callback(xwl_window);
    xwl_surface_damage(xwl_window->xwl_screen, xwl_window->surface,
                       damage_box->x1 - present_window->drawable.x, damage_box->y1 - present_window->drawable.y,
                       damage_box->x2 - damage_box->x1, damage_box->y2 - damage_box->y1);
    if (xwl_window->tearing_control) { // tearing-control协议实现锯齿控制
        uint32_t hint;
        if (event->async_may_tear) // 立即翻页
            hint = WP_TEARING_CONTROL_V1_PRESENTATION_HINT_ASYNC;
        else // 等下一个vblank再翻页
            hint = WP_TEARING_CONTROL_V1_PRESENTATION_HINT_VSYNC;
        wp_tearing_control_v1_set_presentation_hint(xwl_window->tearing_control, hint);
    }
    // 提交显示请求
    wl_surface_commit(xwl_window->surface);
    if (!vblank->sync_flip) {
        // 处理翻页事件，利用wayland请求和事件处理顺序，收到该sync事件时，上述请求已执行完成
        xwl_present_window->sync_callback = wl_display_sync(xwl_window->xwl_screen->display);
        wl_callback_add_listener(xwl_present_window->sync_callback, &xwl_present_sync_listener, &event->vblank);
    }
    wl_display_flush(xwl_window->xwl_screen->display);
    xwl_window->present_flipped = TRUE;
    return TRUE;
}

// frame事件处理函数
static void frame_callback(void *data, struct wl_callback *callback, uint32_t time){
    struct xwl_window *xwl_window = data;
    wl_callback_destroy (xwl_window->frame_callback);
    xwl_window->frame_callback = NULL;
    if (xwl_window->xwl_screen->present) {
        xwl_present_for_each_frame_callback(xwl_window, xwl_present_frame_callback);
        // If xwl_window_create_frame_callback was called from xwl_present_frame_callback,
        // need to make sure all fallback timers are adjusted correspondingly.
        if (xwl_window->frame_callback)
            xwl_present_for_each_frame_callback(xwl_window, xwl_present_reset_timer);
    }
}

// 单个窗口的frame事件处理
void xwl_present_frame_callback(struct xwl_present_window *xwl_present_window){
    xorg_list_del(&xwl_present_window->frame_callback_list);
    // 处理翻页事件，发送PresentCompleteNotify事件，并处理下一个vblank请求
    xwl_present_msc_bump(xwl_present_window);
    // we do not need the timer anymore for this frame, reset it for potentially the next one
    xwl_present_reset_timer(xwl_present_window);
}

static void dri3_flush_present_events(struct loader_dri3_drawable *draw) {
   if (draw->special_event) {
      xcb_generic_event_t    *ev;
      while ((ev = xcb_poll_for_special_event(draw->conn, draw->special_event)) != NULL) {
         xcb_present_generic_event_t *ge = (void *) ev;
         if (!dri3_handle_present_event(draw, ge))
            break;
      }
   }
}

static bool dri3_handle_present_event(struct loader_dri3_drawable *draw, xcb_present_generic_event_t *ge){
   switch (ge->evtype) {
   case XCB_PRESENT_CONFIGURE_NOTIFY: {
      xcb_present_configure_notify_event_t *ce = (void *) ge;
      if (ce->pixmap_flags & PresentWindowDestroyed) {
         free(ge);
         return false;
      }
      draw->width = ce->width;
      draw->height = ce->height;
      // 调用egl_dri3_set_drawable_size重新设置画布大小。（egl_dri3_vtable）
      draw->vtable->set_drawable_size(draw, draw->width, draw->height);
      // 调用dri2_invalidate_drawable使纹理失效，（dri2FlushExtension）
      draw->ext->flush->invalidate(draw->dri_drawable);
      break;
   }
   case XCB_PRESENT_COMPLETE_NOTIFY: {
      xcb_present_complete_notify_event_t *ce = (void *) ge;
      // 处理协议的32位的序号，serial为低32位的序号，本地序号保存在sbc交换缓冲计数器中
      if (ce->kind == XCB_PRESENT_COMPLETE_KIND_PIXMAP) {
         uint64_t recv_sbc = (draw->send_sbc & 0xffffffff00000000LL) | ce->serial;
        // Only assume wraparound if that results in exactly the previous SBC + 1,
        // otherwise ignore received SBC > sent SBC to avoid calculating bogus target MSC values in loader_dri3_swap_buffers_msc
         if (recv_sbc <= draw->send_sbc)
            draw->recv_sbc = recv_sbc;
         else if (recv_sbc == (draw->recv_sbc + 0x100000001ULL))
            draw->recv_sbc = recv_sbc - 0x100000000ULL;

         // When moving from flip to copy, we assume that we can allocate in a more optimal way 
         // if we don't need to cater for the display controller.
         if (ce->mode == XCB_PRESENT_COMPLETE_MODE_COPY &&
             draw->last_present_mode == XCB_PRESENT_COMPLETE_MODE_FLIP) {
            // 硬件翻页功能失效可能使窗口尺寸发生变化导致，尝试重新分配缓冲
            for (int b = 0; b < ARRAY_SIZE(draw->buffers); b++) {
               if (draw->buffers[b])
                  draw->buffers[b]->reallocate = true;
            }
         }
         // If the server tells us that our allocation is suboptimal, we reallocate once.
         if (ce->mode == XCB_PRESENT_COMPLETE_MODE_SUBOPTIMAL_COPY &&
             draw->last_present_mode != ce->mode) {
            for (int b = 0; b < ARRAY_SIZE(draw->buffers); b++) {
               if (draw->buffers[b])
                  draw->buffers[b]->reallocate = true;
            }
         }
         draw->last_present_mode = ce->mode;
         draw->ust = ce->ust;
         draw->msc = ce->msc;
      } else if (ce->serial == draw->eid) {
         draw->notify_ust = ce->ust;
         draw->notify_msc = ce->msc;
      }
      break;
   }
   case XCB_PRESENT_EVENT_IDLE_NOTIFY: {
      xcb_present_idle_notify_event_t *ie = (void *) ge;
      int b;
      for (b = 0; b < ARRAY_SIZE(draw->buffers); b++) {
         struct loader_dri3_buffer *buf = draw->buffers[b];
         if (buf && buf->pixmap == ie->pixmap)
            buf->busy = 0; // 标记buffer为空闲，可复用了
      }
      break;
   }
   }
   free(ge);
   return true;
}