1.3.1 Composite extension

// mutter检测xwayland已经启动后，对x11 display进行初始化，做为X11 server的client，初始化相关扩展
// 扩展包括：xsync, xshape, xcomposite, xdamage, xfixes, xi
gboolean meta_display_init_x11_finish (MetaDisplay *display, GAsyncResult  *result, GError **error){
  MetaX11Display *x11_display = meta_x11_display_new (display, error);
  if (!x11_display)
    return FALSE;
 
  display->x11_display = x11_display;
  g_signal_emit (display, display_signals[X11_DISPLAY_SETUP], 0);
  meta_x11_display_create_guard_window (x11_display);
 
  if (!display->display_opening){
    g_signal_emit (display, display_signals[X11_DISPLAY_OPENED], 0);
    // 创建composite window，属性为CWOverrideRedirect，保存在x11_display->wm_cm_selection_window
    meta_x11_display_set_cm_selection (x11_display);
    // 对已有的顶层窗口，增加页框窗口。（窗口管理器功能）
    meta_display_manage_all_xwindows (display);
    // 对根窗口发送XCompositeRedirectSubwindows，为其子窗口创建CompWindow
    meta_compositor_redirect_x11_windows (display->compositor);
  }
  return TRUE;
}

// update一般为CompositeRedirectManual
int compRedirectSubwindows(ClientPtr pClient, WindowPtr pWin, int update){
    CompSubwindowsPtr csw = GetCompSubwindows(pWin);
    CompClientWindowPtr ccw;
    WindowPtr pChild;
    // Only one Manual update is allowed
    if (csw && update == CompositeRedirectManual)
        for (ccw = csw->clients; ccw; ccw = ccw->next)
            if (ccw->update == CompositeRedirectManual)
                return BadAccess;
    // Allocate per-client per-window structure
    // The client *could* allocate multiple, but while supported, it is not expected to be common
    ccw = malloc(sizeof(CompClientWindowRec));
    if (!ccw)
        return BadAlloc;
    ccw->id = FakeClientID(pClient->index);
    ccw->update = update;
    // Now make sure there's a per-window structure to hang this from
    if (!csw) {
        csw = malloc(sizeof(CompSubwindowsRec));
        if (!csw) {
            free(ccw);
            return BadAlloc;
        }
        csw->update = CompositeRedirectAutomatic;
        csw->clients = 0;
        dixSetPrivate(&pWin->devPrivates, CompSubwindowsPrivateKey, csw);
    }
    // Redirect all existing windows，相反方向遍历，compRedirectWindow涉及窗口栈的变化
    for (pChild = pWin->lastChild; pChild; pChild = pChild->prevSib) {
        // 创建window的compWindow，以及独立的pixmap
        int ret = compRedirectWindow(pClient, pChild, update);
        if (ret != Success) {
            // skip
        }
    }
    // Hook into subwindows list
    ccw->next = csw->clients;
    csw->clients = ccw;
    if (!AddResource(ccw->id, CompositeClientSubwindowsType, pWin))
        return BadAlloc;
    if (ccw->update == CompositeRedirectManual) {
        csw->update = CompositeRedirectManual;
        // tell damage extension that damage events for this client are critical output
        DamageExtSetCritical(pClient, TRUE);
        pWin->inhibitBGPaint = TRUE;
    }
    return Success;
}

// 为pWin创建compWindow，update为CompositeRedirectManual
int compRedirectWindow(ClientPtr pClient, WindowPtr pWin, int update){
    CompWindowPtr cw = GetCompWindow(pWin);
    CompClientWindowPtr ccw;
    CompScreenPtr cs = GetCompScreen(pWin->drawable.pScreen);
    WindowPtr pLayerWin;
    Bool anyMarked = FALSE;
    if (pWin == cs->pOverlayWin) {
        return Success;
    }
    if (!pWin->parent)
        return BadMatch;
    // Only one Manual update is allowed
    if (cw && update == CompositeRedirectManual)
        for (ccw = cw->clients; ccw; ccw = ccw->next)
            if (ccw->update == CompositeRedirectManual)
                return BadAccess;
    // Allocate per-client per-window structure
    // The client *could* allocate multiple, but while supported, it is not expected to be common
    ccw = malloc(sizeof(CompClientWindowRec));
    if (!ccw)
        return BadAlloc;
    ccw->id = FakeClientID(pClient->index);
    ccw->update = update;
    // Now make sure there's a per-window structure to hang this from
    if (!cw) {
        cw = malloc(sizeof(CompWindowRec));
        if (!cw) {
            free(ccw);
            return BadAlloc;
        }
        // 创建damage
        cw->damage = DamageCreate(compReportDamage, compDestroyDamage, DamageReportNonEmpty,
                                  FALSE, pWin->drawable.pScreen, pWin);
        if (!cw->damage) {
            free(ccw);
            free(cw);
            return BadAlloc;
        }
        // 标记与pWin重叠的窗口，有重叠则返回true
        // miMarkOverlappedWindows深度遍历pWin和相邻窗口以及所有子窗口是否有重叠
        // miMarkWindow记录与pWin有重叠的窗口尺寸
        anyMarked = compMarkWindows(pWin, &pLayerWin);
        RegionNull(&cw->borderClip);
        cw->update = CompositeRedirectAutomatic;
        cw->clients = 0;
        cw->oldx = COMP_ORIGIN_INVALID;
        cw->oldy = COMP_ORIGIN_INVALID;
        cw->damageRegistered = FALSE;
        cw->damaged = FALSE;
        cw->pOldPixmap = NullPixmap;
        dixSetPrivate(&pWin->devPrivates, CompWindowPrivateKey, cw);
    }
    ccw->next = cw->clients;
    cw->clients = ccw;
    if (!AddResource(ccw->id, CompositeClientWindowType, pWin))
        return BadAlloc;
    if (ccw->update == CompositeRedirectManual) {
        if (!anyMarked)
            anyMarked = compMarkWindows(pWin, &pLayerWin);
        if (cw->damageRegistered) {
            DamageUnregister(cw->damage);
            cw->damageRegistered = FALSE;
        }
        cw->update = CompositeRedirectManual;
    }
    else if (cw->update == CompositeRedirectAutomatic && !cw->damageRegistered) {
        if (!anyMarked)
            anyMarked = compMarkWindows(pWin, &pLayerWin);
    }
    // 创建或者销毁pixmap，此创建为window创建一个pixmap
    if (!compCheckRedirect(pWin)) {
        FreeResource(ccw->id, RT_NONE);
        return BadAlloc;
    }
    if (anyMarked)
        // 有重叠，则处理重叠窗口部分
        compHandleMarkedWindows(pWin, pLayerWin);
    return Success;
}

static void compHandleMarkedWindows(WindowPtr pWin, WindowPtr pLayerWin) {
    ScreenPtr pScreen = pWin->drawable.pScreen;
    // miValidateTree，根据窗口树，计算需要重绘的窗口及其区域
    (*pScreen->ValidateTree) (pLayerWin->parent, pLayerWin, VTOther);
    // miHandleValidateExposures，深度优先，先绘制边框，再绘制背景，然后发送Expose事件给客户端绘制内容
    (*pScreen->HandleExposures) (pLayerWin->parent);
    // xf86XVPostValidateTree，视频扩展协议使用，该场景不处理
    if (pScreen->PostValidateTree)
        (*pScreen->PostValidateTree) (pLayerWin->parent, pLayerWin, VTOther);
}

typedef struct _damage {
    DamagePtr pNext;     // pixmap的damage列表
    DamagePtr pNextWin;  // window的damage列表
    RegionRec damage;    // 变化区域，初始化为空

    DamageReportLevel damageLevel; // 触发report的级别，DamageCreate时赋值
    Bool isInternal; // DamageCreate时赋值
    void *closure;   // DamageCreate时赋值
    Bool isWindow;   // 是否为窗口的damage，既可以是Window，也可以是pixmap，DamageRegister时赋值
    DrawablePtr pDrawable;  // 画布指针（window or pixmap），DamageRegister时赋值

    DamageReportFunc damageReport;
    DamageDestroyFunc damageDestroy;

    Bool reportAfter;
    RegionRec pendingDamage;    // will be flushed post submission at the latest
    ScreenPtr pScreen;
} DamageRec;

// 触发report的级别
typedef enum _damageReportLevel {
    DamageReportRawRegion,    // 传递新增的变化区域给damageReport，每次都触发report
    DamageReportDeltaRegion,  // 有变化，传递变化区域
    DamageReportBoundingBox,  // 边界有变化，传递整个damage区域
    DamageReportNonEmpty,     // 由空到非空变化，传递整个damage区域
    DamageReportNone
} DamageReportLevel;

// Damage的回调函数
const DamageScreenFuncsRec miFuncs = {
    miDamageCreate, miDamageRegister, miDamageUnregister,  miDamageDestroy
};

void miDamageCreate(DamagePtr pDamage) {}
 
void miDamageRegister(DrawablePtr pDrawable, DamagePtr pDamage){
    if (pDrawable->type == DRAWABLE_WINDOW)
        // 深度优先遍历窗口，更新窗口的序列号：pWin->drawable.serialNumber = NEXT_SERIAL_NUMBER;
        TraverseTree((WindowPtr)pDrawable, damageRegisterVisit, NULL);
    else
        pDrawable->serialNumber = NEXT_SERIAL_NUMBER;
}
 
void miDamageUnregister(DrawablePtr pDrawable, DamagePtr pDamage) {
    if (pDrawable->type == DRAWABLE_WINDOW)
        TraverseTree((WindowPtr)pDrawable, damageRegisterVisit, NULL);
    else
        pDrawable->serialNumber = NEXT_SERIAL_NUMBER;
}
 
void miDamageDestroy(DamagePtr pDamage) {}

// DamageReportNonEmpty，可显示区域变化时，当区域不为空时，调用compReportDamage
// cw->damage = DamageCreate(compReportDamage,compDestroyDamage,DamageReportNonEmpty,FALSE, pWin->drawable.pScreen, pWin);
 
static void compReportDamage(DamagePtr pDamage, RegionPtr pRegion, void *closure){
    WindowPtr pWin = (WindowPtr) closure;
    ScreenPtr pScreen = pWin->drawable.pScreen;
    CompScreenPtr cs = GetCompScreen(pScreen);
    CompWindowPtr cw = GetCompWindow(pWin);
    if (!cs->pendingScreenUpdate) {
        // 插入工作队列，在主线程下次迭代时处理
        QueueWorkProc(compScreenUpdate, serverClient, pScreen);
        cs->pendingScreenUpdate = TRUE;
    }
    cw->damaged = TRUE;
    // 标记祖父窗口，子孙窗口已被修改，即pWin->damagedDescendants = TRUE;
    compMarkAncestors(pWin);
}
 
static Bool compScreenUpdate(ClientPtr pClient, void *closure){
    ScreenPtr pScreen = closure;
    CompScreenPtr cs = GetCompScreen(pScreen);
    // 递归调用深度优先递归调用，若窗口有变化，调用compWindowUpdateAutomatic更新窗口
    compPaintChildrenToWindow(pScreen->root);
    cs->pendingScreenUpdate = FALSE; // Next damage will restore the worker
    return TRUE;
}

void compPaintChildrenToWindow(WindowPtr pWin){
    WindowPtr pChild;
    if (!pWin->damagedDescendants)
        return;
    // 将所有子窗口内容合成至父窗口中
    for (pChild = pWin->lastChild; pChild; pChild = pChild->prevSib)
        compPaintWindowToParent(pChild);
    pWin->damagedDescendants = FALSE;
}

static void compPaintWindowToParent(WindowPtr pWin){
    // 递归处理窗口的所有子窗口
    compPaintChildrenToWindow(pWin);
    if (pWin->redirectDraw != RedirectDrawNone) {
        CompWindowPtr cw = GetCompWindow(pWin);
        if (cw->damaged) {
            // 将窗口内容合成至父窗口中
            compWindowUpdateAutomatic(pWin);
            cw->damaged = FALSE;
        }
    }
}

static void compWindowUpdateAutomatic(WindowPtr pWin) {
    CompWindowPtr cw = GetCompWindow(pWin);
    ScreenPtr pScreen = pWin->drawable.pScreen;
    WindowPtr pParent = pWin->parent;
    PixmapPtr pSrcPixmap = (*pScreen->GetWindowPixmap) (pWin);
    PictFormatPtr pSrcFormat = PictureWindowFormat(pWin);
    PictFormatPtr pDstFormat = PictureWindowFormat(pWin->parent);
    int error;
    RegionPtr pRegion = DamageRegion(cw->damage);
    PicturePtr pSrcPicture = CreatePicture(0, &pSrcPixmap->drawable, pSrcFormat, 0, 0, serverClient, &error);
    XID subwindowMode = IncludeInferiors;
    PicturePtr pDstPicture = CreatePicture(0, &pParent->drawable, pDstFormat, CPSubwindowMode, &subwindowMode, serverClient, &error);

    // First move the region from window to screen coordinates
    RegionTranslate(pRegion, pWin->drawable.x, pWin->drawable.y);
    // Clip against the "real" border clip
    RegionIntersect(pRegion, pRegion, &cw->borderClip);
    // Now translate from screen to dest coordinates
    RegionTranslate(pRegion, -pParent->drawable.x, -pParent->drawable.y);
    // Clip the picture
    SetPictureClipRegion(pDstPicture, 0, 0, pRegion);
    // And paint
    CompositePicture(PictOpSrc, pSrcPicture, 0, pDstPicture, 0, 0, 0, 0, pSrcPixmap->screen_x - pParent->drawable.x, pSrcPixmap->screen_y - pParent->drawable.y, pSrcPixmap->drawable.width, pSrcPixmap->drawable.height);
    FreePicture(pSrcPicture, 0);
    FreePicture(pDstPicture, 0);
    // Empty the damage region.  This has the nice effect of rendering the translations above harmless
    DamageEmpty(cw->damage);
}

void CompositePicture(CARD8 op, PicturePtr pSrc, PicturePtr pMask, PicturePtr pDst,
                 INT16 xSrc, INT16 ySrc, INT16 xMask, INT16 yMask,
                 INT16 xDst, INT16 yDst, CARD16 width, CARD16 height) {
    PictureScreenPtr ps = GetPictureScreen(pDst->pDrawable->pScreen);

    ValidatePicture(pSrc);
    if (pMask)
        ValidatePicture(pMask);
    ValidatePicture(pDst);

    op = ReduceCompositeOp(op, pSrc, pMask, pDst, xSrc, ySrc, width, height);
    if (op == PictOpDst)
        return;
    // 调用damageComposite -> glamor_composite 合成图像
    (*ps->Composite) (op, pSrc, pMask, pDst,
                      xSrc, ySrc, xMask, yMask, xDst, yDst, width, height);
}

static Bool register_damage(WindowPtr window) {
    // 为window创建damage，当damage区域由空至非空时，触发report操作
    DamagePtr damage = DamageCreate(damage_report, damage_destroy, DamageReportNonEmpty, FALSE, window->drawable.pScreen, window);
    if (damage == NULL) {
        ErrorF("Failed creating damage\n");
        return FALSE;
    }
    // 为window注册damage
    DamageRegister(&window->drawable, damage);
    DamageSetReportAfterOp(damage, TRUE);
    dixSetPrivate(&window->devPrivates, &xwl_damage_private_key, damage);
    return TRUE;
}

// window显示内容有变化，则加入xwl_screen->damage_window_list列表中，在blockHandler回调中处理
static void damage_report(DamagePtr pDamage, RegionPtr pRegion, void *data){
    WindowPtr window = data;
    struct xwl_window *xwl_window = xwl_window_get(window);
    struct xwl_screen *xwl_screen;
    if (!xwl_window)
        return;
    xwl_screen = xwl_window->xwl_screen;
    if (xwl_window->present_flipped) {
        // This damage is from a Present flip, which already committed a new buffer for the surface,
        // so we don't need to do anything in response
        RegionEmpty(DamageRegion(pDamage));
        xorg_list_del(&xwl_window->link_damage);
        xwl_window->present_flipped = FALSE;
        return;
    }
    if (xorg_list_is_empty(&xwl_window->link_damage))
        xorg_list_add(&xwl_window->link_damage, &xwl_screen->damage_window_list);
}

// 在主线程中由BlockHandler调用，处理上次迭代时等待处理的事务
static void block_handler(void *data, void *timeout) {
    struct xwl_screen *xwl_screen = data;
    xwl_screen_post_damage(xwl_screen);
    xwl_dispatch_events (xwl_screen);
}

// 向Wayland compositor发送damage请求，由Wayland compositor处理damage内容
static void xwl_screen_post_damage(struct xwl_screen *xwl_screen){
    struct xwl_window *xwl_window, *next_xwl_window;
    struct xorg_list commit_window_list;
    xorg_list_init(&commit_window_list);
    // 遍历damage_window_list列表中所有的window，这些window的显示内容均有变化
    xorg_list_for_each_entry_safe(xwl_window, next_xwl_window, &xwl_screen->damage_window_list, link_damage) {
        // If we're waiting on a frame callback from the server, don't attach a new buffer.
        if (xwl_window->frame_callback)
            continue;
        if (!xwl_window->allow_commits)
            continue;
        if (xwl_screen->glamor && !xwl_glamor_allow_commits(xwl_window))
            continue;
        // 向Wayland compositor发送damage请求，更新damage区域，并将自身的damage区域清空
        xwl_window_post_damage(xwl_window);
        // 从damage_window_list列表中删除window
        xorg_list_del(&xwl_window->link_damage);
        // 并将window加入commit_window_list临时列表中
        xorg_list_append(&xwl_window->link_damage, &commit_window_list);
    }

    if (xorg_list_is_empty(&commit_window_list))
        return;
    if (xwl_glamor_needs_buffer_flush(xwl_screen))
        glamor_block_handler(xwl_screen->screen);
    // 遍历commit_window_list提交列表，向Wayland compositor提交请求，处理damage内容
    xorg_list_for_each_entry_safe(xwl_window, next_xwl_window, &commit_window_list, link_damage) {
        wl_surface_commit(xwl_window->surface);
        // 从commit_window_list列表中删除window
        xorg_list_del(&xwl_window->link_damage);
    }
}