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

[Even Rouault]

Le vendredi 08 juillet 2011 16:09:31, Jorge Arévalo a écrit :
> 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

For the sake of simplicity, let's assume that the datatype is byte (if not, 
just multiply all values by GDALGetDataType(eDT) / 8),

Yes, nPixelOffset = 1, nLineOffset = nBufferXSize, nBandOffset = nBufferXSize * 
nBufferYSize.

(nBandOffset is for GDALDatasetRasterIO())

> 
> 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

Yes, nPixelOffset = 1, nLineOffset = nBufferXSize * nBands, nBandOffset = 
nBufferXSize

> 
> 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

You meant :

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

right ?

And nPixelOffset = nBands, nLineOffset = nBands * nBufferXSize, nBandOffset = 1

> 
> Now my doubt.
> 
> Does "byte offset" mean the byte space between the start of 2 valid
> values in pData?

The maths will speak better...

If you output buffer starts at address pStart, for band b (numbered from 1) the 
value of the pixel at line j (numbered from 0), column i (numbered from 0) of 
the output buffer will be stored at :

pStart + i * nPixelSpace + j * nLineSpace + (b-1) * nBandSpace

So nPixelSpace is the difference between the address of a pixel and the pixel 
at its right on the same line.

> 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)

Not sure to follow you, hopefully the above explinations will answer your 
question ;-)

> 
> Isn't it the most common situation? In which situation has sense
> having "gaps" between pixel values, or at the end of a row?

Sometimes you just want to override the values of an allocated buffer with 
greater extent, so you need to provide a so-called "line stride" that is 
greater than nBufferXSize.

> 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.".

I guess it means that if you need to read from different bands with multiple 
calls to RasterIO() but in the same buffer, you can tweak nPixelSize and 
nLineOffset to let enough space for data from different bands and match the 
organization of the data as you've designed it.

> 
> Thanks in advance, and best regards.
> Jorge