From 9c01c385124e80cce56504b57d5fc17b863ee601 Mon Sep 17 00:00:00 2001
From: Max Horn
Date: Wed, 18 May 2011 14:06:56 +0200
Subject: TINSEL: Document pDispList OBJECT linked list 'trick'

---
 engines/tinsel/background.cpp | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

(limited to 'engines/tinsel/background.cpp')

diff --git a/engines/tinsel/background.cpp b/engines/tinsel/background.cpp
index 4f0623df6a..79a8d4a148 100644
--- a/engines/tinsel/background.cpp
+++ b/engines/tinsel/background.cpp
@@ -162,6 +162,21 @@ OBJECT *GetPlayfieldList(int which) {
 	pPlayfield = pCurBgnd->fieldArray + which;
 
 	// return the display list pointer for this playfield
+	//
+	// HACK: We pretend that pPlayfield is an OBJECT here, by explicitly
+	// casting a pointer to it (resp. to its first member) to an OBJECT
+	// pointer.
+	// Of course it isn't, but its first member is pDispList, an OBJECT
+	// pointer, just like the first member of an OBJECT is pNext, also
+	// an OBJECT pointer. This (classic) trick allows us to use
+	// pPlayfield as a fake anchor element for the linked list of
+	// objects pDispList points to, which in turn simplifies some list
+	// manipulation code. Alas, this is prone to confuse aliasing
+	// analysis in compilers, and also silly developers like myself ;).
+	// So at the very least, I figured we should document this trick
+	// here explicitly.
+	// Personally, I would prefer if we got rid of this trick, e.g. by
+	// introducing an explicit anchor element.
 	return (OBJECT *)&pPlayfield->pDispList;
 }
 
-- 
cgit v1.2.3