http://bugs.winehq.org/show_bug.cgi?id=9775
--- Comment #31 from Tobias Jakobi liquid.acid@gmx.net 2008-07-03 12:20:36 --- (In reply to comment #30)
I would also shorten the test's comment to one or few lines, but it's just my opinion.
I don't know how to fit all important information in two lines. Even if I dropped the MSDN refs it would be much longer than two lines.
I do know that msdn references are not in very good favor in general, I think previously there even have been patches specifically removing msdn links. There is some sense in it, to discourage reliance on msdn for purpose of documenting the code (or there is a risk that after 5 years code documentation consists of references to materials that went the same way as e.g. DX6 docs went).
I don't think this is a valid point. It's true that Microsoft doesn't provide the docs anymore on their homepage, BUT there are still mirrors on the net providing these old docs for download. I have currently docs for DX7, 8 and 9 installed - from which only 9 is provided by MS currently (docs for 8 and 7 were removed already).
Also I don't think devs are reverse engineering the entire DX lib by watching what call XYZ does (like nouveau figures out how the nvidia hw works). If I'm going to fix say DX6 code I need the DX6 SDK anyway.
I do understand that paving the code with MSDN links isn't very clever, but at least allow it to contain some refs so you can look it up if you want further information (and have access to the docs).
-------------------------------------------------
Let's take a look at my comment block:
Test the behaviour of the IDirect3DDevice8::CreateImageSurface method.
What method is tested...
Expected behaviour (and also documented in the original DX8 docs) is that the call returns a surface with the SYSTEMMEM pool type. Games like Max Payne 1 and 2 which use Direct3D8 calls depend on this behaviour.
What the method should do and which apps that rely on the behaviour. Includes remark why this behaviour should be correct (further verified by the testcase)
A short remark in the DX9 docs however states that the pool of the returned surface object is of type SCRATCH. This is misinformation and results in screenshots not appearing in the savegame loading menu of both games mentioned above (engine tries to display a texture from the scratch pool).
Explaining why the bug popped up in the the first place: misinformation from DX9 Also xplaining the results of the wrong implementation.
This test verifies that the behaviour described in the original D3D8 docs is the correct one.
Summing up..
For more information about this issue, see the MSDN: D3D9 docs: "Converting to Direct3D 9" D3D9 reference: "IDirect3DDevice9::CreateOffscreenPlainSurface" D3D8 reference: "IDirect3DDevice8::CreateImageSurface"
Now for this one is important: it's COMPLETLY optional! As stated "for MORE information" - you don't need this to understand the core of the bug and the bugfix. Only a hint...
----------------------------------------
I'm always grateful of hints in sourcecode. Makes it easier for someone with no insight in the code to get involved. Usually you spend hours skimming through code until you get an idea what it is doing. I find it very helpful to get some clues where I can find further (documenting) information to get an overview. It also helps me speeding up my google searches, because with the overview I know what to search for (because I now know the right keywords).
I'm currently writing another testcase for a different D3D8 method (LockBox, the current implementation isn't really behaving how it should) and up to now it has almost no sourcecode comments - and it's not going to contain any refs to the MSDN, simply because it wouldn't make any sense there (the docs don't describe when locks should succeed or fail). So don't think I added the three refs just for fun, they are actually there to support/help further development.
Ultimately it's Alexandre Julliard who commits (or not) the patch. BTW a good way to know the status of patches / rejection reason is to ask him (nick julliard) on #winehackers, he is usually very responsive when online. It sometimes happens that patches get lost in high traffic.
Sure, but I was hoping to get some sort of ACK from a guru like you ;-) And I don't want to spam on wine-patches if the patches aren't applied anyway.
Greets, Tobias