From 83a28d5af2dbdac839d303e1fd40cc0220d51240 Mon Sep 17 00:00:00 2001
From: "Enrico Weigelt, metux IT consult" <info@metux.net>
Date: Thu, 3 Jul 2025 14:41:14 +0200
Subject: [PATCH 1/2] miext: damage: document DamageScreenFuncsRec

This struct (and associated functions) needs to be part of public driver ABI,
so video drivers can get notifications on damage certain operations, but
there hasn't been any documentation on it.

Signed-off-by: Enrico Weigelt, metux IT consult <info@metux.net>
---
 miext/damage/damage.h | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/miext/damage/damage.h b/miext/damage/damage.h
index 525b2db5d..b3185c18f 100644
--- a/miext/damage/damage.h
+++ b/miext/damage/damage.h
@@ -46,6 +46,18 @@ typedef void (*DamageScreenRegisterFunc) (DrawablePtr, DamagePtr);
 typedef void (*DamageScreenUnregisterFunc) (DrawablePtr, DamagePtr);
 typedef void (*DamageScreenDestroyFunc) (DamagePtr);
 
+/* @public
+ *
+ * @brief Driver callbacks for getting notified on several damage calls
+ *
+ * The pointer to this struct can be obtained via DamageGetScreenFuncs().
+ * Drivers can inject themselves here, in order to get notified on
+ * DamageCreate(), DamageRegister(), DamageUnregister(), DamageDestroy().
+ *
+ * This should ONLY be touched by video drivers, nobody else.
+ *
+ * So far the only one using it is the proprietary NVidia driver.
+ */
 typedef struct _damageScreenFuncs {
     DamageScreenCreateFunc Create;
     DamageScreenRegisterFunc Register;

From ce2bcc0a4f5aa9c728d0329ea0618c005c255d30 Mon Sep 17 00:00:00 2001
From: "Enrico Weigelt, metux IT consult" <info@metux.net>
Date: Thu, 3 Jul 2025 14:51:11 +0200
Subject: [PATCH 2/2] miext: damage: tolerate NULL pointers in
 DamageScreenFuncsRec

For now that case doensn't practically happen yet - all fields are at
least assigned to some default/dummy function. But in the future, we
might wanna get rid of dummies.

From now on, video drivers are allowed to assign them to NULL, if they
don't wanna have the default implementations and nothing happening
at all instead (no more need for having their own empty dummies)

Signed-off-by: Enrico Weigelt, metux IT consult <info@metux.net>
---
 miext/damage/damage.c | 14 ++++++++++----
 miext/damage/damage.h |  3 +++
 2 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/miext/damage/damage.c b/miext/damage/damage.c
index 4d146efaf..f54621caf 100644
--- a/miext/damage/damage.c
+++ b/miext/damage/damage.c
@@ -1714,7 +1714,8 @@ DamageCreate(DamageReportFunc damageReport,
     pDamage->damageDestroy = damageDestroy;
     pDamage->pScreen = pScreen;
 
-    (*pScrPriv->funcs.Create) (pDamage);
+    if (pScrPriv->funcs.Create)
+        pScrPriv->funcs.Create (pDamage);
 
     return pDamage;
 }
@@ -1755,7 +1756,8 @@ DamageRegister(DrawablePtr pDrawable, DamagePtr pDamage)
         pDamage->isWindow = FALSE;
     pDamage->pDrawable = pDrawable;
     damageInsertDamage(getDrawableDamageRef(pDrawable), pDamage);
-    (*pScrPriv->funcs.Register) (pDrawable, pDamage);
+    if (pScrPriv->funcs.Register)
+        pScrPriv->funcs.Register (pDrawable, pDamage);
 }
 
 void
@@ -1774,7 +1776,8 @@ DamageUnregister(DamagePtr pDamage)
 
     damageScrPriv(pScreen);
 
-    (*pScrPriv->funcs.Unregister) (pDrawable, pDamage);
+    if (pScrPriv->funcs.Unregister)
+        pScrPriv->funcs.Unregister (pDrawable, pDamage);
 
     if (pDrawable->type == DRAWABLE_WINDOW) {
         WindowPtr pWindow = (WindowPtr) pDrawable;
@@ -1817,7 +1820,10 @@ DamageDestroy(DamagePtr pDamage)
 
     if (pDamage->damageDestroy)
         (*pDamage->damageDestroy) (pDamage, pDamage->closure);
-    (*pScrPriv->funcs.Destroy) (pDamage);
+
+    if (pScrPriv->funcs.Destroy)
+        pScrPriv->funcs.Destroy (pDamage);
+
     RegionUninit(&pDamage->damage);
     RegionUninit(&pDamage->pendingDamage);
     free(pDamage);
diff --git a/miext/damage/damage.h b/miext/damage/damage.h
index b3185c18f..cd8053890 100644
--- a/miext/damage/damage.h
+++ b/miext/damage/damage.h
@@ -54,6 +54,9 @@ typedef void (*DamageScreenDestroyFunc) (DamagePtr);
  * Drivers can inject themselves here, in order to get notified on
  * DamageCreate(), DamageRegister(), DamageUnregister(), DamageDestroy().
  *
+ * The fields may be assigned to NULL, if no action at all is wanted.
+ * (by default assigned to default implementations)
+ *
  * This should ONLY be touched by video drivers, nobody else.
  *
  * So far the only one using it is the proprietary NVidia driver.