From 984da40fbb1e9479edda2e9e9e8746456e420594 Mon Sep 17 00:00:00 2001 From: "Enrico Weigelt, metux IT consult" Date: Mon, 30 Sep 2024 17:59:28 +0200 Subject: [PATCH] doc: document that ScreenRec->DestroyPixmap() shouldn't be called directly Direct calls to ScreenRec->DestroyPixmap() is fragile and blocks cleaning up the wrapping jungle, so use the proper dix function instead. While this function originally wasn't made for that purpose (and so we have an useless parameter here, and the naming isn't entirely correct), it's the best effort we have right now, without breaking existing API: it's already exported since long time, so drivers can be easily converted and still work with both new and older Xserver ABI versions. Retrospectively, this already should have been done 20 years ago. Signed-off-by: Enrico Weigelt, metux IT consult Part-of: --- doc/Xserver-spec.xml | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/Xserver-spec.xml b/doc/Xserver-spec.xml index 7736cb292..20c6cff85 100644 --- a/doc/Xserver-spec.xml +++ b/doc/Xserver-spec.xml @@ -3057,6 +3057,14 @@ must deallocate the PixmapRec and all attached devPrivate blocks. If successful, it returns TRUE. See Xserver/fb/fbpixmap.c for the sample server implementation. +Consumers should never ever call that proc directly, but call dixDestroyPixmap() instead. + + +If it's ever wrapped (by an extension), the wrapping handler must be written +in a way that it can always be called, even when the private structures are in +an half-initialized state (error pathes), so no extra unwrapping magic necessary. + +
Bool