TPngImage help needed for vague docs

[gwideman 0]

The documentation for Vcl.Imaging.pngimage.TPngImage (http://docwiki.embarcadero.com/Libraries/Athens/en/Vcl.Imaging.pngimage.TPngImage) says:

 

Quote

Use TPngImage to load and manipulate PNG (Portable Network Graphics) graphics. . It is not required to use the TPngImage class directly. If you need your application to accepts PNG images, simply add the pngimage unit in the uses list. This operation ensures that the PNG graphic format is registered in the VCL.

 

Say what?!?  First it says to use TPngImage, then is says you don't need to use it.  Then it goes on to say that if you add pngimage to the uses clause, something helpful happens, but doesn't say what.

 

I'd appreciate if someone could spell out what is this favored method of using TPngImage without actually using it.

[JonRobertson 72]

Once you add pngimage to the uses clause of any unit, the TPNGImage class is registered with TPicture, which enables your application to load and save PNG images. This is done in the initialization section of pngimage.pas (TPicture.RegisterFileFormat('PNG', 'Portable Network Graphics', TPngImage);).

 

This provides PNG support to any class that uses TPicture to load or save impages, for example: TImage.Picture.LoadFromFile.

 

If you want more control over the image itself, then declare and use an instance of TPNGImage and the provided methods and properties to load, save, or modify the PNG image as desired.

[gwideman 0]

14 minutes ago, JonRobertson said:

Once you add pngimage to the uses clause of any unit, the TPNGImage class is registered with TPicture, which enables your application to load and save PNG images.  [...]

 

Thanks for your rapid response!   This seems like the key information.  The docs for TPicture  are also a little unhelpful:

Quote

TPicture is a TGraphic container, used to hold a graphic, the type of which is specified in the Graphic property. It is used in place of a TGraphic [in what context?] if the graphic can be of any TGraphic class. LoadFromFile and SaveToFile are polymorphic. For example, if the TPicture is holding an Icon, it is valid to LoadFromFile a bitmap file, where the class TIcon can only read .ICO files.

If the TPicture contains a bitmap graphic, the Bitmap property specifies the graphic. If the TPicture contains an icon graphic, the Icon property specifies the graphic. If the TPicture contains a metafile graphic, the Metafile property specifies the graphic.

The properties of TPicture indicate the type of graphic that the picture object contains, and its size. The methods of TPicture are used to load, save, and manipulate graphics.

 

So does this apparatus expect us to first set the Graphic property to the desired type of TGraphic, and then perform operations like LoadFromFile?  The description makes it sound like this causes LoadFromFile to convert from the file's type of image data to the type of image data you've preset in Graphic.

 

Or is it OK starting with nothing set for Graphic, and then just calling LoadFromFile creates the object that Graphic points to, of a type that matches the input image data? 

 

And are the Bitmap, Icon, Metafile, and WICImage properties pointers to separate actual objects? Or are they just more-specifically typed pointers to the same object that Graphic points to (ie: at most one would be valid).  What happens if the graphic type is not one of the default ones, as with TPNGImage and TJPEGImage?

 

Thanks for any further clues on how to work with this apparatus rather than against it, or via random flounder :-).

[Lajos Juhász 293]

5 hours ago, gwideman said:

Or is it OK starting with nothing set for Graphic, and then just calling LoadFromFile creates the object that Graphic points to, of a type that matches the input image data? 

When the image format is registered the loadfromfile will create the class required to load the image.

 

5 hours ago, gwideman said:

And are the Bitmap, Icon, Metafile, and WICImage properties pointers to separate actual objects? Or are they just more-specifically typed pointers to the same object that Graphic points to (ie: at most one would be valid).  What happens if the graphic type is not one of the default ones, as with TPNGImage and TJPEGImage?

 

They are used the same way. Depending on the file type you have loaded the required object is created.

[JonRobertson 72]

8 hours ago, gwideman said:

So does this apparatus expect us to first set the Graphic property to the desired type of TGraphic, and then perform operations like LoadFromFile?  The description makes it sound like this causes LoadFromFile to convert from the file's type of image data to the type of image data you've preset in Graphic.

The Graphic property does not represent the "type of graphic". Think of it more as a helper class that is capable of loading multiple graphic formats. The only "conversion" is unpacking the image file format, such as color depth, color map or palette, compression, etc, to a Windows Bitmap GDI object. Once an image is loaded, SaveToFile or SaveToStream may be used to write the image to a different format.

 

8 hours ago, gwideman said:

Or is it OK starting with nothing set for Graphic, and then just calling LoadFromFile creates the object that Graphic points to, of a type that matches the input image data? 

Yes. If you look at the source for TPicture.LoadFromFile, you will see that it internally uses TGraphic to load an image. Looking at the source code is an excellent way to find answers, particularly if the documentation seems lacking or confusing.

 

3 hours ago, Lajos Juhász said:

8 hours ago, gwideman said:

And are the Bitmap, Icon, Metafile, and WICImage properties pointers to separate actual objects? Or are they just more-specifically typed pointers to the same object that Graphic points to (ie: at most one would be valid).  What happens if the graphic type is not one of the default ones, as with TPNGImage and TJPEGImage?

They are used the same way. Depending on the file type you have loaded the required object is created.

To expand a little, loading an image only creates one instance of a graphic class. Bitmaps, icons, metafiles, and WIC images are not the same type of image. Try loading a TImage with a PNG (Image1.Picture.LoadFromFile('image.png')) and using the Icon property to save it as an icon (Image1.Picture.Icon.SaveToFile('image.ico')). The exception "Icon image is not valid" will be raised. However, using Picture.SaveToFile('image1.ico') does work, at least in the test that I did.

 

8 hours ago, gwideman said:

Thanks for any further clues on how to work with this apparatus rather than against it, or via random flounder :-)

Random flounder is an excellent way to learn. Create a new VCL project, throw a TImage on the form, and try various things to see what works and what doesn't. Take some time to look at the underlying source code. Start with Vcl.Graphics.pas for the foundation, then look at the Vcl.Imaging units, such as GIFImg.pas, JPEG.pas, and PNGImage.pas.

 

That is what I did while writing this message.