[gdal-dev] Meaning of nPixelSpace/nLineSpace in IRasterIO

[Jorge Arévalo]

Hello,

I'm not sure of the meaning of nPixelSpace, nLineSpace IRasterIO args.
>From GDAL doc I read:

nPixelSpace: The byte offset from the start of one pixel value in
pData to the start of the next pixel value within a scanline. If
defaulted (0) the size of the datatype eBufType is used.

nLineSpace: The byte offset from the start of one scanline in pData to
the start of the next. If defaulted (0) the size of the datatype
eBufType * nBufXSize is used.

and

The nPixelSpace and nLineSpace parameters allow reading into or
writing from unusually organized buffers. This is primarily used for
buffers containing more than one bands raster data in interleaved
format.

I know there are, basically, 3 interleave formats:

BSQ (INTERLEAVE=BAND)
BIL (INTERLEAVE=LINE)
BIP (INTERLEAVE=PIXEL)

Assuming a 3-bands (rgb) 4x4 raster, the pData array would look like
this ("|" used only to mark the end of a row):

BSQ: r1 r1 r1 r1 | r2 r2 r2 r2 | r3 r3 r3 r3 | r4 r4 r4 r4 | g1 g1 g1
g1 | g2 g2 g2 g2 | g3 g3 g3 g3 | g4 g4 g4 g4 g4 | b1 b1 b1 b1 | b2 b2
b2 b2 | b3 b3 b3 b3 | b4 b4 b4 b4

BIL: r1 r1 r1 r1 | g1 g1 g1 g1 | b1 b1 b1 b1 | r2 r2 r2 r2 | g2 g2 g2
g2 | b2 b2 b2 b2 | r3 r3 r3 r3 | g3 g3 g3 g3 | b3 b3 b3 b3 | r4 r4 r4
r4 | g4 g4 g4 g4 | b4 b4 b4 b4

BIP: r1 g1 b1 r2 | g2 b2 r3 g3 | b3 r4 g4 b4 | r1 g1 b1 r2 | g2 b2 r3
g3 | b3 r4 g4 b4 | r1 g1 b1 r2 | g2 b2 r3 g3 | b3 r4 g4 b4 | r1 g1 b1
r2 | g2 b2 r3 g3 | b3 r4 g4 b4

Now my doubt.

Does "byte offset" mean the byte space between the start of 2 valid
values in pData? For example, the space between r1 and g1 in BIP
format. I guess if there's no trailing bits in the array (all the bits
are payload) the byte offset between the start of 2 valid values is
always the size of the data type. Then simply r1 = pData[0] and g1 =
pData[1] (BIP format)

Isn't it the most common situation? In which situation has sense
having "gaps" between pixel values, or at the end of a row? I think I
don't really understand the sentence: "This is primarily used for
buffers containing more than one bands raster data in interleaved
format.".

Thanks in advance, and best regards.
Jorge

-- 
Jorge Arévalo
Internet & Mobility Division, DEIMOS
jorge.arevalo at deimos-space.com
http://es.linkedin.com/in/jorgearevalo80
http://mobility.grupodeimos.com/
http://gis4free.wordpress.com
http://geohash.org/ezjqgrgzz0g