Documentation is unclear about how blit_into and related functions work.

[GoogleCodeExporter]

The API docs imply that AbstractImage.blit_into() always works with any type of 
AbstractImage.  This is certainly not the case.  Anything that inherits from 
AbstractImage and doesn't override blit_into (ImageData, CompressedImageData, 
BufferImage, etc) will fail when you try to blit_into it.  Looking at the 
source, it appears that the only thing that can be a target of blit_into is in 
fact a Texture and the things that inherit from it.

This is fine, it just also really needs to be documented.

Original issue reported on code.google.com by icefo...@gmail.com on 20 May 2014 at 1:16

[GoogleCodeExporter]

I agree, it's not clear what can do blit_into and it's been a recurring 
question in the mailing list.

Besides the actual method documentation, perhaps some notes could be added in:

 http://pyglet.org/doc-current/programming_guide/image.html#the-abstractimage-hierarchy

Thanks for the report, patches are welcome!

Original comment by useboxnet on 21 May 2014 at 5:58

• Changed state: Accepted
• Added labels: Component-Docs

[GoogleCodeExporter]

Okay, I'll see if I can come up with some useful documentation.  One thing I 
still am not entirely clear on though, what is the behavior of blit_image if 
the coordinates of the source image are not entirely inside the target image?  
With the target image being a Texture, it will raise an error if the source 
image coordinates fall entirely outside the target image, but if it's partially 
inside, what does happen/what should happen for various classes?  I have some 
knowledge of OpenGL, but not really enough to feel comfortable with these sorts 
of edge cases.  

Also, from the mailing list posts it sounds like the intended behavior is for 
blitting arbitrary things onto a Texture to work fine, but to not allow 
blitting onto a software surface/ImageData?  The rationale being if you're 
making the CPU do your image composition you're making a mistake anyway?  Just 
trying to make sure I'm understanding what's going on.  

Thanks again,
Simon

Original comment by icefo...@gmail.com on 23 May 2014 at 12:36

[GoogleCodeExporter]

Can you ask for help on the mailing list?

Thanks for helping to improve pyglet!

Original comment by useboxnet on 31 May 2014 at 7:44

• Changed state: Blocked

[GoogleCodeExporter]

Added some documentation; it's not much, but better than nothing.  
image-docs.patch makes some minor updates to the programming guide and the 
AbstractImage.blit_into() docs.

I also noticed a handful of minor formatting errors in the return type 
notations in a few places.  rettype-fixes.patch fixes these.

Original comment by icefo...@gmail.com on 23 Jun 2014 at 10:16

Attachments:

• image-docs.patch
• rettype-fixes.patch

[GoogleCodeExporter]

Brilliant, thanks!

Original comment by useboxnet on 23 Jun 2014 at 10:18

• Changed state: Started
• Added labels: Type-Patch