Due to an error with how I called stretch_blit, I wound up debugging and I discovered that on most platforms in all cases stretch_blit calls _al_stretch_blit, so naturally I was looking it over to see if anything was wrong with it. I came to the lines where it actually stretches the bitmap and I discovered this line (allegro/src/c/cstretch.c line 404) :

      (*stretch_line)(bmp_write_line(dst, y) + dxofs, src->line[sy] + sxofs);

Now the destination bitmap is guaranteed to be a memory bitmap by these lines (src/c/cstretch.c lines 259-263) - actually if do_stretch_blit is NULL in the source bitmap's vtable then the destination could be any kind of bitmap.

   /* vtable hook; not called if dest is a memory surface */   
   if (src->vtable->do_stretch_blit && !is_memory_bitmap(dst)) {
      src->vtable->do_stretch_blit(src, dst, sx, sy, sw, sh, dx, dy, dw, dh, masked);
      return;
   }

The problem is that the type of the source bitmap is not checked for at all, and it is accessed using the line pointer, which the manual says it is not safe to do for non memory bitmaps :

The manual goes on to elaborate a little bit :

   void linear_screen_putpixel(BITMAP *bmp, int x, int y, int color)
   {
      bmp_select(bmp);
      bmp_write8((unsigned long)bmp->line[y]+x, color);
   }

So in this case, they use the line pointer to write to the screen, but the manual goes on and says when this will not work :

However, I tested stretch_blit on Vista using a video bitmap as the source and a memory bitmap as the destination, and nothing bad happened at all, so I'm confused.

The manual says it's wrong to use line pointers on non memory bitmaps, but _al_stretch_blit does exactly that.

So is it safe to use line pointers on any bitmap, or isn't it?

Append
Well, I looked at stretch_blit in the manual, and it says :

However, if that is true, then why are there entries in gfx_capabilities for the following flags :

This indicates that the source may be a system or video bitmap when drawing onto another video bitmap. I wish the manual would stop contradicting itself.

Is it correct to assume that given all the information so far, that when the destination bitmap is a memory bitmap, then the source bitmap can (should) only be a memory bitmap? That would fit _al_stretch_blit's assumption about using a line pointer on the source bitmap, however, the source code of _al_stretch_blit should reflect that if it is true.

Append 2
Bueller?

Append 3
So, to review :
1) The manual says it's wrong to use line pointers on non memory bitmaps, but _al_stretch_blit does exactly that.
2) The manual says that for stretch_blit that the source must be a memory bitmap, but there are flags in gfx_capabilities that indicate the possibility of hardware accelerated stretching from system and video bitmaps to video bitmaps.

Apparent options :
1) Change the manual entry for stretch_blit to say that the source bitmap must be a memory bitmap except when gfx_capabilities has the following flags set (as appropriate) :
GFX_HW_VRAM_STRETCH_BLIT
GFX_HW_SYS_STRETCH_BLIT
GFX_HW_VRAM_STRETCH_BLIT_MASKED
GFX_HW_SYS_STRETCH_BLIT_MASKED

2) Modify _al_stretch_blit to work for any combination of bitmap types. This would require using bmp_read_line on the source to read a line into a temporary array and then stretching the line normally.

3) Modify _al_stretch_blit to ASSERT that the source is a memory bitmap.

So, any opinions on this?

Append 4
Since I haven't gotten any replies to this, I guess I will take it to the [AD] mailing list and see if I get any replies there.

Isn't that a contradiction though? The flags indicate that Allegro is capable of it, as far as I know. They do say that the destination is the screen though, and not just any video bitmap, but I don't personally know if there is a difference.

Technically, it should be as simple as using an if else statement to preserve the code that is currently there for memory source bitmaps and allow for the source to be a system or video bitmap. The only other thing necessary would be to make a copy of the line from the source system/video bitmap and pass that to the 'stretch_line' function pointer instead of 'src->line[sy] + sxofs'.

The code I'm referring to is at the end of src/c/cstretch.c in the al_stretch_blit function on lines 399-413 :

It would become something like :

It may be slightly slower due to the allocation and memcpy, but that's for stretching from system and video bitmaps where it was previously unsupported, and the original routine is only altered by an if check, which is negligible.

I haven't forgotten about this if you were wondering, I just haven't gotten to it yet. What with Allegro 4.4.2 coming out recently, there's no real rush anyway.