Simplify examples

[andersmelander]

The current suite of example applications does a wonderful job of showcasing what can be done with Graphics32. However they are not very good at exemplifying how things are done.

Mostly it is possible to glean from the examples how things are done, but one has to mentally filter out all the supporting code such as UI control logic, "clever" tricks and additional gimmicks that doesn't really pertain to the core subject of the example. The result is that it takes an unnecessary effort to understand how to accomplish a specific task with Graphics32 - even for seasoned users of the library.

I propose that the examples be simplified so they are more approachable when learning Graphics32.

The more complex examples can be moved to a Showcases folder so we retain that ability.

A few examples of what I mean:

• BlendVsMerge

  • ModifyAlphaValues()
    Modifies bitmaps in place to creates a horizontal alpha gradient. A few comments should explain why this is done.
  • Custom paint stage to draw checker board.
    This task is so common it should be built into TImage32, but that's another story.
  • The method demonstrating the main feature doesn't contain a single comment explaining the actual work done. Only a few caveats are vaguely explained.

• PixelCombine
  Display alternating pixels between foreground and background using a vertical grid pattern:

procedure TFormPixelCombine.PC_Pattern(F: TColor32; var B: TColor32; M: TColor32);
begin
  PatCount := 1 - PatCount;
  if PatCount = 0 then B := F;
end;

I'm sure the above saves a few microseconds, but using a boolean toggle would have saved the user from wondering what the heck is going on.

• TextureBlend
  Not even sure what it is this one demonstrates...

• ArrowHead
  Animation and collision detection. Impressive but hardly relevant to arrow heads...

etc. etc.

---

The AntiAliasing example is actually a really good showcase - and it is so simple and well commented that it's also a good example of how to draw different shapes.

[CWBudde]

I like the idea of having a limited set of examples. And with examples I really mean examples, that show the new users how to use the library.

Ideally, it would be done in some sort of didactic manner. Starting from very basic to complex.

Eventually we could also have some sort of a mega demo, which demonstrates all possibilities, but not too much.

This said, the current examples are not that bad. They just need some more comments and explanations.

We should still keep them, but probably sort a few out into a new "GR32 Showcase" project. That would also increase the count of open source delphi projects, eventually making the language more visible in programming laguage indices such as red monk.

[CWBudde]

I had now looked through a few of the examples. Compared to other open source projects they are already quite well structured and documented at most places. I have now added a few more comments. There are still many examples which lack a documentation.

If time permits, I will go through the existing examples and comment them one by one. In order to get some v2.0 done, I'd say we should keep all the examples for that release. We should put new examples on the roadmap for any of the next releases.

[andersmelander]

I agree. Can you create a Milestone for post 2.0 work and assign this one to it?

[AngusJohnson]

Regarding examples, there is currently no provision for DPI scaling by the OS and consequently all the samples are being image scaled by the Windows when Large Text is selected (see Ease of Access | Display in Windows Settings). This causes noticeable blurring when scaling >= 150% which is obviously problematic when we're interested in assessing image quality.
Anyhow, I suggest compiling a simple Manifest resource (Manifest.zip) into all the samples.

[andersmelander]

I suggest compiling a simple Manifest resource (Manifest.zip) into all the samples.

Good idea. I would tune the manifest a bit though.

I'm seeing in your manifest:

• Application name: myOrganization.myDivision.mySampleApp
  I would suggest: graphics32.demo

• Version: 6.0.0.0
  I would suggest: [none]

• Virtualized file and registry access: Yes
  I would suggest: No

• UAC run level: [not specified]
  I would suggest: As Invoker

• DPI awareness: Legacy system aware
  I would suggest: [same] and add the dpiAwareness=system tag.

• OS compatbility: Vista, 7, 8 & 8.1
  I would suggest: [same] and add Windows 10.

• Dependencies: MSCC 6.0.0.0
  I would suggest: [same]

[andersmelander]

@micha137 I believe the reference to manifest.res you removed in commit 98b8ebc was part of the changes @AngusJohnson made for this issue. I just think Angus forgot to commit the manifest.res file - probably because .res is in the .ignore list.

[micha137]

Sorry, I didn't see the connection to this issue. Then manifest.res needs to be added, together with the reference(s) again.

[andersmelander]

I think @AngusJohnson can do that once he's ready to commit the file. For now it's more important to leave the repository in a consistent state.

[AngusJohnson]

I think @AngusJohnson can do that once he's ready to commit the file.

I presume you were referring to manifest.res file which I've just uploaded

[x2nie]

Hi. by the way, current Lazarus supports *.dpr and *.dfm.
So, about examples, maybe separated *.lfm & *.lpr can be eliminated. To reduce code polution, just maybe.

[andersmelander]

maybe separated *.lfm & *.lpr can be eliminated.

That would be excellent. Thanks for the info.