File: pycdgAux.py

package info (click to toggle)
pykaraoke 0.7.5-1.2%2Bdeb9u1
  • links: PTS, VCS
  • area: main
  • in suites: stretch
  • size: 2,608 kB
  • sloc: python: 6,696; ansic: 577; makefile: 71; sh: 46
file content (551 lines) | stat: -rw-r--r-- 25,228 bytes parent folder | download | duplicates (5)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
#
# Copyright (C) 2010 Kelvin Lawson (kelvinl@users.sourceforge.net)
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

""" This module is the Python implementation of the auxiliary classes
and functions which have been moved into C for performance reasons.
On the off-chance a C compiler is not available or not reliable for
some reason, you can use this implementation instead. """

import pygame
try:
    import Numeric as N
except ImportError:
    import numpy.oldnumeric as N

# CDG Command Code
CDG_COMMAND             = 0x09

# CDG Instruction Codes
CDG_INST_MEMORY_PRESET      = 1
CDG_INST_BORDER_PRESET      = 2
CDG_INST_TILE_BLOCK         = 6
CDG_INST_SCROLL_PRESET      = 20
CDG_INST_SCROLL_COPY        = 24
CDG_INST_DEF_TRANSP_COL     = 28
CDG_INST_LOAD_COL_TBL_0_7   = 30
CDG_INST_LOAD_COL_TBL_8_15  = 31
CDG_INST_TILE_BLOCK_XOR     = 38

# Bitmask for all CDG fields
CDG_MASK            = 0x3F

# This is the size of the display as defined by the CDG specification.
# The pixels in this region can be painted, and scrolling operations
# rotate through this number of pixels.
CDG_FULL_WIDTH      = 300
CDG_FULL_HEIGHT     = 216

# This is the size of the array that we operate on.  We add an
# additional border on the right and bottom edge of 6 and 12 pixels,
# respectively, to allow for display shifting.  (It's not clear from
# the spec which colour should be visible when the display is shifted
# to the right or down.  We say it should be the border colour.)

# This is the size of the screen that is actually intended to be
# visible.  It is the center area of CDG_FULL.  The remaining border
# area surrounding it is not meant to be visible.
CDG_DISPLAY_WIDTH   = 288
CDG_DISPLAY_HEIGHT  = 192

# Screen tile positions
# The viewable area of the screen (288x192) is divided into
# 24 tiles (6x4 of 49x51 each). This is used to only update
# those tiles which have changed on every screen update,
# thus reducing the CPU load of screen updates. A bitmask of
# tiles requiring update is held in cdgPlayer.UpdatedTiles.
# This stores each of the 4 columns in separate bytes, with 6 bits used
# to represent the 6 rows.
TILES_PER_ROW           = 6
TILES_PER_COL           = 4
TILE_WIDTH              = CDG_DISPLAY_WIDTH / TILES_PER_ROW
TILE_HEIGHT             = CDG_DISPLAY_HEIGHT / TILES_PER_COL

COLOUR_TABLE_SIZE       = 16

class CdgPacket:
    """ This class just represents a single 24-byte packet read from
    the CDG stream.  It's not used outside this module. """
    
    def __init__(self, packetData):
        self.command = packetData[0]
        self.instruction = packetData[1]
        #self.parityQ = packetData[2:4]
        self.data = packetData[4:20]
        #self.parity = packetData[20:24]

class CdgPacketReader:
    """ This class does the all work of reading packets from the CDG
    file, and evaluating them to fill in pixels in a Numeric array.
    Its public interface is in five methods. """

    # In this class, we are aggressive with the use of the leading
    # double underscore, Python's convention to indicate private
    # members.  We do this to clearly delineate the private data and
    # methods from the public data and methods, since only the public
    # members are of interest to the C port of this class.  (Though,
    # in practice, the C port follows this class structure quite
    # closely, including duplicating the private members.)
    
    def __init__(self, cdgData, mapperSurface):
        self.__cdgData = cdgData
        self.__cdgDataPos = 0

        # This is just for the purpose of mapping colors.
        self.__mapperSurface = mapperSurface

        self.Rewind()
        
    def Rewind(self):
        """ Rewinds the stream to the beginning, and resets all
        internal state in preparation for decoding the tiles
        again. """
        
        self.__cdgDataPos = 0

        # Initialise the colour table. Set a default value for any
        # CDG files that don't actually load the colour table
        # before doing something with it.
        defaultColour = 0
        self.__cdgColourTable = [defaultColour] * COLOUR_TABLE_SIZE

        self.__justClearedColourIndex = -1
        self.__cdgPresetColourIndex = -1
        self.__cdgBorderColourIndex = -1
        # Support only one transparent colour
        self.__cdgTransparentColour = -1

        # These values are used to implement screen shifting.  The CDG
        # specification allows the entire screen to be shifted, up to
        # 5 pixels right and 11 pixels down.  This shift is persistent
        # until it is reset to a different value.  In practice, this
        # is used in conjunction with scrolling (which always jumps in
        # integer blocks of 6x12 pixels) to perform
        # one-pixel-at-a-time scrolls.
        self.__hOffset = 0
        self.__vOffset = 0
        
        # Build a 306x228 array for the pixel indeces, including border area
        self.__cdgPixelColours = N.zeros((CDG_FULL_WIDTH, CDG_FULL_HEIGHT))

        # Build a 306x228 array for the actual RGB values. This will
        # be changed by the various commands, and blitted to the
        # screen now and again. But the border area will not be
        # blitted, only the central 288x192 area.
        self.__cdgSurfarray = N.zeros((CDG_FULL_WIDTH, CDG_FULL_HEIGHT))

        # Start with all tiles requiring update
        self.__updatedTiles = 0xFFFFFFFFL

    def MarkTilesDirty(self):
        """ Marks all the tiles dirty, so that the next call to
        GetDirtyTiles() will return the complete list of tiles. """
        
        self.__updatedTiles = 0xFFFFFFFFL

    def GetDirtyTiles(self):
        """ Returns a list of (row, col) tuples, corresponding to all
        of the currently-dirty tiles.  Then resets the list of dirty
        tiles to empty. """
        
        tiles = []
        if self.__updatedTiles != 0:
            for col in range(TILES_PER_COL):
                for row in range(TILES_PER_ROW):
                    if (self.__updatedTiles & ((1 << row) << (col * 8))):
                        tiles.append((row, col))

        self.__updatedTiles = 0
        return tiles

    def GetBorderColour(self):
        """ Returns the current border colour, as a mapped integer
        ready to apply to the surface.  Returns None if the border
        colour has not yet been specified by the CDG stream. """
        
        if self.__cdgBorderColourIndex == -1:
            return None
        return self.__cdgColourTable[self.__cdgBorderColourIndex]

    def DoPackets(self, numPackets):
        """ Reads numPackets 24-byte packets from the CDG stream, and
        processes their instructions on the internal tables stored
        within this object.  Returns True on success, or False when
        the end-of-file has been reached and no more packets can be
        processed."""
        
        for i in range(numPackets):
            # Extract the nexxt packet
            packd = self.__getNextPacket()
            if not packd:
                # No more packets.  Return False, but only if we
                # reached this condition on the first packet.
                return (i != 0)

            self.__cdgPacketProcess (packd)

        return True

    def FillTile(self, surface, row, col):
        """ Fills in the pixels on the indicated one-tile surface
        (which must be a TILE_WIDTH x TILE_HEIGHT sized surface) with
        the pixels from the indicated tile. """
        
        # Calculate the row & column starts/ends
        row_start = 6 + self.__hOffset + (row * TILE_WIDTH)
        row_end = 6 + self.__hOffset + ((row + 1) * TILE_WIDTH)
        col_start = 12 + self.__vOffset + (col * TILE_HEIGHT)
        col_end = 12 + self.__vOffset + ((col + 1) * TILE_HEIGHT)
        pygame.surfarray.blit_array( \
            surface, \
            self.__cdgSurfarray[row_start:row_end, col_start:col_end])


    # The remaining methods are all private; they are not part of the
    # public interface.

    # Read the next CDG command from the file (24 bytes each)
    def __getNextPacket(self):
        packetData = map(ord, self.__cdgData[self.__cdgDataPos : self.__cdgDataPos + 24])
        self.__cdgDataPos += 24
        if (len(packetData) == 24):
            return CdgPacket(packetData)
        else:
            self.__cdgDataPos = len(self.__cdgData)
            return None

    # Decode and perform the CDG commands in the indicated packet.
    def __cdgPacketProcess (self, packd):
        if (packd.command & CDG_MASK) == CDG_COMMAND:
            inst_code = (packd.instruction & CDG_MASK)
            if inst_code == CDG_INST_MEMORY_PRESET:
                self.__cdgMemoryPreset (packd)
            elif inst_code == CDG_INST_BORDER_PRESET:
                self.__cdgBorderPreset (packd)
            elif inst_code == CDG_INST_TILE_BLOCK:
                self.__cdgTileBlockCommon(packd, xor = 0)
            elif inst_code == CDG_INST_SCROLL_PRESET:
                self.__cdgScrollPreset (packd)
            elif inst_code == CDG_INST_SCROLL_COPY:
                self.__cdgScrollCopy (packd)
            elif inst_code == CDG_INST_DEF_TRANSP_COL:
                self.__cdgDefineTransparentColour (packd)
            elif inst_code == CDG_INST_LOAD_COL_TBL_0_7:
                self.__cdgLoadColourTableCommon (packd, 0)
            elif inst_code == CDG_INST_LOAD_COL_TBL_8_15:
                self.__cdgLoadColourTableCommon (packd, 1)
            elif inst_code == CDG_INST_TILE_BLOCK_XOR:
                self.__cdgTileBlockCommon(packd, xor = 1)
            else:
                # Don't use the error popup, ignore the unsupported command
                ErrorString = "CDG file may be corrupt, cmd: " + str(inst_code)
                print (ErrorString)

    # Memory preset (clear the viewable area + border)
    def __cdgMemoryPreset (self, packd):
        colour = packd.data[0] & 0x0F
        repeat = packd.data[1] & 0x0F

        # The "repeat" flag is nonzero if this is a repeat of a
        # previously-appearing preset command.  (Often a CDG will
        # issue several copies of this command in case one gets
        # corrupted.)

        # We could ignore the entire command if repeat is nonzero, but
        # our data stream is not 100% reliable, since it might have
        # come from a bad rip.  So we should honor every preset
        # command; but we shouldn't waste CPU time clearing the screen
        # repeatedly, needlessly.  So we store a flag indicating the
        # last color that we just cleared to, and don't bother
        # clearing again if it hasn't changed.
        
        if colour == self.__justClearedColourIndex:
            return
        self.__justClearedColourIndex = colour

        # Our new interpretation of CD+G Revealed is that memory preset
        # commands should also change the border
        self.__cdgPresetColourIndex = colour
        self.__cdgBorderColourIndex = self.__cdgPresetColourIndex
        
        # Note that this may be done before any load colour table
        # commands by some CDGs. So the load colour table itself
        # actual recalculates the RGB values for all pixels when
        # the colour table changes.

        # Set the border colour for every pixel. Must be stored in 
        # the pixel colour table indeces array, as well as
        # the screen RGB surfarray.

        # NOTE: The preset area--that is, the visible area--starts at
        # (6, 12) and extends to pixel (294, 204).  The border area is
        # the two stripes of 6 pixels on the left and right of the
        # screen, and the stripes of 12 pixels on the top and bottom
        # of the screen.
        
        # The most efficient way of setting the values in a Numeric
        # array, is to create a zero array and do addition on the
        # the border and preset slices.
        self.__cdgPixelColours = N.zeros([CDG_FULL_WIDTH, CDG_FULL_HEIGHT])
        self.__cdgPixelColours[:,:] = self.__cdgPixelColours[:,:] + colour
        
        # Now set the border and preset colour in our local surfarray. 
        # This will be blitted next time there is a screen update.
        self.__cdgSurfarray = N.zeros([CDG_FULL_WIDTH, CDG_FULL_HEIGHT])
        self.__cdgSurfarray[:,:] = self.__cdgSurfarray[:,:] + self.__cdgColourTable[colour]

        self.__updatedTiles = 0xFFFFFFFFL

    # Border Preset (clear the border area only) 
    def __cdgBorderPreset (self, packd):
        colour = packd.data[0] & 0x0F
        if colour == self.__cdgBorderColourIndex:
            return
        
        self.__cdgBorderColourIndex = colour

        # See cdgMemoryPreset() for a description of what's going on.
        # In this case we are only clearing the border area.

        # Set up the border area of the pixel colours array
        self.__cdgPixelColours[:,:12] = N.zeros([CDG_FULL_WIDTH, 12])
        self.__cdgPixelColours[:,:12] = self.__cdgPixelColours[:,:12] + self.__cdgBorderColourIndex
        self.__cdgPixelColours[:,-12:] = N.zeros([CDG_FULL_WIDTH, 12])
        self.__cdgPixelColours[:,-12:] = self.__cdgPixelColours[:,-12:] + self.__cdgBorderColourIndex
        self.__cdgPixelColours[:6,12:-12] = N.zeros([6, CDG_FULL_HEIGHT - 24]) 
        self.__cdgPixelColours[:6,12:-12] = self.__cdgPixelColours[:6,12:-12] + self.__cdgBorderColourIndex
        self.__cdgPixelColours[-6:,12:-12] = N.zeros([6, CDG_FULL_HEIGHT - 24]) 
        self.__cdgPixelColours[-6:,12:-12] = self.__cdgPixelColours[-6:,12:-12] + self.__cdgBorderColourIndex

        # Now that we have set the PixelColours, apply them to
        # the Surfarray.
        lookupTable = N.array(self.__cdgColourTable)
        self.__cdgSurfarray.flat[:] = N.take(lookupTable, N.ravel(self.__cdgPixelColours))

        return

    # CDG Scroll Command - Set the scrolled in area with a fresh colour
    def __cdgScrollPreset (self, packd):
        self.__cdgScrollCommon (packd, copy = False)
        return

    # CDG Scroll Command - Wrap the scrolled out area into the opposite side
    def __cdgScrollCopy (self, packd):
        self.__cdgScrollCommon (packd, copy = True)
        return

    # Common function to handle the actual pixel scroll for Copy and Preset
    def __cdgScrollCommon (self, packd, copy):

        # Decode the scroll command parameters
        data_block = packd.data
        colour = data_block[0] & 0x0F
        hScroll = data_block[1] & 0x3F
        vScroll = data_block[2] & 0x3F
        hSCmd = (hScroll & 0x30) >> 4
        hOffset = (hScroll & 0x07)
        vSCmd = (vScroll & 0x30) >> 4
        vOffset = (vScroll & 0x0F)

        # Scroll Vertical - Calculate number of pixels
        vScrollUpPixels = 0
        vScrollDownPixels = 0
        if vSCmd == 2:
            vScrollUpPixels = 12
        elif vSCmd == 1:
            vScrollDownPixels = 12

        # Scroll Horizontal- Calculate number of pixels
        hScrollLeftPixels = 0
        hScrollRightPixels = 0
        if hSCmd == 2:
            hScrollLeftPixels = 6
        elif hSCmd == 1:
            hScrollRightPixels = 6

        if hOffset != self.__hOffset or vOffset != self.__vOffset:
            # Changing the screen shift.
            self.__hOffset = min(hOffset, 5)
            self.__vOffset = min(vOffset, 11)
            self.__updatedTiles = 0xFFFFFFFFL

        if hScrollLeftPixels == 0 and \
           hScrollRightPixels == 0 and \
           vScrollUpPixels == 0 and \
           vScrollDownPixels == 0:
            # Never mind.
            return

        # Perform the actual scroll. Use surfarray and slicing to make
        # this efficient. A copy scroll (where the data scrolls round)
        # can be achieved by slicing and concatenating again.
        # For non-copy, the new slice is filled in with a new colour.
        if (copy == True):
            if (vScrollUpPixels > 0):
                self.__cdgPixelColours = N.concatenate((self.__cdgPixelColours[:,vScrollUpPixels:], self.__cdgPixelColours[:,:vScrollUpPixels]), 1)
            elif (vScrollDownPixels > 0):
                self.__cdgPixelColours = N.concatenate((self.__cdgPixelColours[:,-vScrollDownPixels:], self.__cdgPixelColours[:,:-vScrollDownPixels]), 1)
            elif (hScrollLeftPixels > 0):
                self.__cdgPixelColours = N.concatenate((self.__cdgPixelColours[hScrollLeftPixels:,:], self.__cdgPixelColours[:hScrollLeftPixels,:]), 0)
            elif (hScrollRightPixels > 0):
                self.__cdgPixelColours = N.concatenate((self.__cdgPixelColours[-hScrollRightPixels:,:], self.__cdgPixelColours[:-hScrollRightPixels,:]), 0)
        elif (copy == False):
            if (vScrollUpPixels > 0):
                copyBlockActualColour = N.zeros([CDG_FULL_WIDTH,vScrollUpPixels]) + self.__cdgColourTable[colour]
                copyBlockColourIndex = N.zeros([CDG_FULL_WIDTH,vScrollUpPixels]) + colour
                self.__cdgPixelColours = N.concatenate((self.__cdgPixelColours[:,vScrollUpPixels:], copyBlockColourIndex), 1)
            elif (vScrollDownPixels > 0):
                copyBlockActualColour = N.zeros([CDG_FULL_WIDTH,vScrollDownPixels]) + self.__cdgColourTable[colour]
                copyBlockColourIndex = N.zeros([CDG_FULL_WIDTH,vScrollDownPixels]) + colour
                self.__cdgPixelColours = N.concatenate((copyBlockColourIndex, self.__cdgPixelColours[:,:-vScrollDownPixels]), 1)
            elif (hScrollLeftPixels > 0):
                copyBlockActualColour = N.zeros([hScrollLeftPixels, CDG_FULL_HEIGHT]) + self.__cdgColourTable[colour]
                copyBlockColourIndex = N.zeros([hScrollLeftPixels, CDG_FULL_HEIGHT]) + colour
                self.__cdgPixelColours = N.concatenate((self.__cdgPixelColours[hScrollLeftPixels:,:], copyBlockColourIndex), 0)
            elif (hScrollRightPixels > 0):
                copyBlockActualColour = N.zeros([hScrollRightPixels, CDG_FULL_HEIGHT]) + self.__cdgColourTable[colour]
                copyBlockColourIndex = N.zeros([hScrollRightPixels, CDG_FULL_HEIGHT]) + colour
                self.__cdgPixelColours = N.concatenate((copyBlockColourIndex, self.__cdgPixelColours[:-hScrollRightPixels,:]), 0)

        # Now that we have scrolled the PixelColours, apply them to
        # the Surfarray.
        
        lookupTable = N.array(self.__cdgColourTable)
        self.__cdgSurfarray.flat[:] = N.take(lookupTable, N.ravel(self.__cdgPixelColours))
        
        # We have modified our local cdgSurfarray. This will be blitted to
        # the screen by cdgDisplayUpdate()
        self.__updatedTiles = 0xFFFFFFFFL

    # Set one of the colour indeces as transparent. Don't actually do anything with this
    # at the moment, as there is currently no mechanism for overlaying onto a movie file.
    def __cdgDefineTransparentColour (self, packd):
        data_block = packd.data
        colour = data_block[0] & 0x0F
        self.__cdgTransparentColour = colour
        return

    # Load the RGB value for colours 0..7 or 8..15 in the lookup table
    def __cdgLoadColourTableCommon (self, packd, table):
        if table == 0:
            colourTableStart = 0
        else:
            colourTableStart = 8
        for i in range(8):
            colourEntry = ((packd.data[2 * i] & CDG_MASK) << 8)
            colourEntry = colourEntry + (packd.data[(2 * i) + 1] & CDG_MASK)
            colourEntry = ((colourEntry & 0x3F00) >> 2) | (colourEntry & 0x003F)
            red = ((colourEntry & 0x0F00) >> 8) * 17
            green = ((colourEntry & 0x00F0) >> 4) * 17
            blue = ((colourEntry & 0x000F)) * 17
            self.__cdgColourTable[i + colourTableStart] = self.__mapperSurface.map_rgb(red, green, blue)
        # Redraw the entire screen using the new colour table. We still use the 
        # same colour indeces (0 to 15) at each pixel but these may translate to
        # new RGB colours. This handles CDGs that preset the screen before actually
        # loading the colour table. It is done in our local RGB surfarray.

        # Do this with the Numeric module operation take() which can replace all
        # values in an array by alternatives from a lookup table. This is ideal as
        # we already have an array of colour indeces (0 to 15). We can create a
        # new RGB surfarray from that by doing take() which translates the 0-15
        # into an RGB colour and stores them in the RGB surfarray.
        lookupTable = N.array(self.__cdgColourTable)
        self.__cdgSurfarray.flat[:] = N.take(lookupTable, N.ravel(self.__cdgPixelColours))

        # An alternative way of doing the above - was found to be very slightly slower.
        #self.__cdgSurfarray.flat[:] =  map(self.__cdgColourTable.__getitem__, self.__cdgPixelColours.flat)

        # Update the screen for any colour changes
        self.__updatedTiles = 0xFFFFFFFFL
        return

    # Set the colours for a 12x6 tile. The main CDG command for display data
    def __cdgTileBlockCommon(self, packd, xor):
        # Decode the command parameters
        data_block = packd.data
        if data_block[1] & 0x20:
            # I don't know why, but some disks seem to stick an extra
            # bit here to mean "ignore this command".
            return

        colour0 = data_block[0] & 0x0F
        colour1 = data_block[1] & 0x0F
        
        column_index = ((data_block[2] & 0x1F) * 12)
        row_index = ((data_block[3] & 0x3F) * 6)

        # Sanity check the x,y offset read from the CDG in case a 
        # corrupted CDG sends us outside of our array bounds
        if (column_index > (CDG_FULL_HEIGHT - 12)):
            column_index = (CDG_FULL_HEIGHT - 12)
        if (row_index > (CDG_FULL_WIDTH - 6)):
            row_index = (CDG_FULL_WIDTH - 6)

        # Set the tile update bitmasks.
        # Note that the screen update area only covers the non-border area
        # excluding the left 6 columns, and top 12 rows. Therefore when
        # calculating whether this block fits into a particular tile, we
        # add 6 or 12 to the x,y positions. Note also that each tile is 6
        # wide and 12 high, so if a block starts less than 6 columns to the
        # left of a block, it will incorporate the adjacent block. Similarly
        # any update starting less than 12 rows above a block, will also
        # incorporate the block below.

        firstRow = max((row_index - 6 - self.__hOffset) / TILE_WIDTH, 0)
        lastRow = (row_index - 1 - self.__hOffset) / TILE_WIDTH

        firstCol = max((column_index - 12 - self.__vOffset) / TILE_HEIGHT, 0)
        lastCol = (column_index - 1 - self.__vOffset) / TILE_HEIGHT

        for col in range(firstCol, lastCol + 1):
            for row in range(firstRow, lastRow + 1):
                self.__updatedTiles |= ((1 << row) << (col * 8))

        # Set the pixel array for each of the pixels in the 12x6 tile.
        # Normal = Set the colour to either colour0 or colour1 depending
        #          on whether the pixel value is 0 or 1.
        # XOR    = XOR the colour with the colour index currently there.
        for i in range (12):
            byte = (data_block[4 + i] & 0x3F)
            for j in range (6):
                pixel = (byte >> (5 - j)) & 0x01
                if xor:
                    # Tile Block XOR
                    if (pixel == 0):
                        xor_col = colour0
                    else:
                        xor_col = colour1
                    # Get the colour index currently at this location, and xor with it
                    currentColourIndex = self.__cdgPixelColours[(row_index + j), (column_index + i)]
                    new_col = currentColourIndex ^ xor_col
                else:
                    # Tile Block Normal
                    if (pixel == 0):
                        new_col = colour0
                    else:
                        new_col = colour1
                # Set the pixel with the new colour. We set both the surfarray
                # containing actual RGB values, as well as our array containing
                # the colour indeces into our colour table.
                self.__cdgSurfarray[(row_index + j), (column_index + i)] = self.__cdgColourTable[new_col]
                self.__cdgPixelColours[(row_index + j), (column_index + i)] = new_col

        # Now the screen has some data on it, so a subsequent clear
        # should be respected.
        self.__justClearedColourIndex = -1
        
        # The changes to cdgSurfarray will be blitted on the next screen update
        return