Now that you understand the intended purpose of LockWindowUpdate, I'm going to tell you why you don't want to use it, not even for its intended purpose!
You have to go back to the historical context in which LockWindowUpdate was created. Rewind back to 16-bit Windows, specifically Windows 3.1. Back in these days, memory was expensive. Video drivers were pretty limited in functionality. There was no DirectX. There was no AlphaBlend function. All you had was a screen buffer. The LockWindowUpdate function let you take control over one window's portion of that screen buffer so you could apply your fancy effects to the window without that window's knowledge.
It's been over a decade since Windows 3.1, and in the meanwhile, we gained DirectX overlays, regional windows, layered windows, alpha blending, desktop composition, all sorts of cool graphical effects that weren't available back in the old days. In particular, those layered windows and regional windows pretty much let you do nearly all of the stuff you would have wanted to do with LockWindowUpdate anyway. If you want to draw a highlight around a window, you can position a regional window around it. If you want to draw a drag image over a window, you can just create layered window and position it over the target window. Give the layered window a region and whatever fancy alpha channel you want, and let the graphics engine do the heavy lifting of alpha blending and composition. Even better, the layered window can extend outside the window you are dragging over, something that LockWindowUpdate can't do. (You can see this effect in Windows XP if you do a "select all" in an Explorer window and drag the entire selection around the screen. Notice that the drag image is not constrained to the boundaries of the window you are dragging over.)
What's more, in the exciting new composited world of Vista's desktop window manager, LockWindowUpdate is even less desirable. Locking a particular window for update isn't so bad since the desktop window manager can just give you the backing bitmap for the window. But if you lock the entire screen (which I've seen may people do), the desktop window manager needs to compose all of the windows into an actual bitmap that it can give you when you call GetDCEx with the DCX_LOCKWINDOWUPDATE flag. The desktop window manager does composition on the fly with the help of DirectX and accelerated video drivers. The result of all this composition normally goes straight to the screen without actually residing in a "composited" bitmap anyway. But if you lock the screen and ask for a DC to it, the desktop window manager needs to emulate the old behavior and give you access to something that represents what you would have gotten if there were no composition in the first place. That ain't cheap.
Epilogue. I'm not sure if this series was a success or not. My goal was just to help people use LockWindowUpdate more effectively and guide them towards alternatives when LockWindowUpdate is the wrong tool for the job. In other words, it's an article about LockWindowUpdate, not function documentation. I tried to keep the presentation light, but I guess my jokes fell flat, and people just used them as a springboard for negative comments.
And extra thanks to the people who took it as an opportunity to complain about the documentation. I mean, duh, if the documentation were perfect, I wouldn't have written this series in the first place. Though these people also neglected to read all of the documentation; they looked only at the function description page. There's more to documentation than dry function descriptions, people! The function description is a reference; you go there when you already know what's going on and you just need to fine-tune a detail. The real learning happens in the overviews and articles. If you want to learn how to operate your radio, you don't read the schematic first.
I think Ronald D. Moore is really onto something when he says, "You have to be tough enough to listen to the podcast."
Thanks for the series! I had never heard of LockWindowUpdate until now…and so I’m imagining all the intriguing-but-performance-ruining things I might be able to do with it.
Your comments about the DWM in Vista whetted my appitite, though. I’d love to read a series chatting about that and how to do strange things like rescale all the windows on your system, or rotate them in 3D!
Battlestar Galactica reference! Woo hoo! Love that show. Here is a suggestion for unhelpful comments … a system where we can mod them down.
Raymond: "I’m not sure if this series was a success or not."
Of course it was. As I saw from the comments not only I but more people who actually develop in Win32 really learned something.
Even the overview theme should give positive results: motivate readers to reread the overviews from time to time can be considered success.
Thank you!
Nice series, Raymond. Thanks!
Thanks for the series, Raymond. Don’t let the negative commenters get you down.
Raymond, i’m not sure what you mean by "regional windows"… is that non-rectangular windows e.g. as in
http://msdn2.microsoft.com/en-us/library/ms997507.aspx (?)
Does that mean that using GetDC(NULL) to get a temporary DC to call functions such as GetTextMetrics is a very wrong? If yes, what should be done instead? Thanks.
Here, I’ll update the documentation for LockWindowUpdate:
"LockWindowUpdate – Deprecated"
Done. The ultimate "use at your own risk" tag.
Re: reading all the documentation.
When the function description page doesn’t tell you what you need to know and it doesn’t have any useful links. Internet search may not have the answer especially if you don’t know what question to ask. How do you find the answer within the multiple gigabytes of documentation without reading all of it? (How long would it take to read all of the MSDN content?)
I think that Larry Lard is right — those who want to complain about some aspect of a topic are naturally more vocal than the silent appreciation of many.
And maybe the doc writers who read these comments will keep them in mind the next time they write new documentation, and do it better.
The comments don’t represent a valid scientific poll, of course!
Thanks for the pointer to layered and regional windows. I have wondered how to do a nice drag and drop display.
Awesome series, Raymond. Not only does it teach one specific aspect, but it also helps teach the thought pattern — I love the idea of the social history around the APIs. As an architect/technologist, I love seeing the line of questioning and thought that you take so I can apply it elsewhere.
Rock on, mightily rock on,
Ned, A fellow wearer-of-ties.
These series are great and highlight the history of the API. At the same time, with as good as the MSDN is, they also highlight big gaping holes in the documentation. How many other methods in the Win32 API are there that we aren’t supposed to use (and aren’t marked as deprecated.) Should I do a google search and read 3 articles on each API call before using it?
Just a brief note about its INTENDED USE might be helpful and then references to other ways to accomplish the same thing if it is deprecated…
You posted a kind of blogger manifesto some times ago that explained all the things your blog isn’t and all the things you are not and are not able to act on.
There should be a reader manifesto too:
– Not all things we say is meant for you to act on.
– We assume people at MS read this and may act on it.
– We have accuracy at heart. If something is not as clear as we think it should be, we will say so.
– The high-quality of content magnifies any defect. See previous point.
– We voice our opinions. Take them or leave them, it’s your choice. No one is twisting your arm. (Urm, okay, some are, but we know who they are.)
But I really think MS should review their model of the documentation reader if your comment is any indication of their position. Most people I know read the function documentation first and only go to the lengthy articles if they need more details.
Caveats, obsolete functions, and the like should go in the function documentation, not be buried in some explanatory overview. (Warning: I did not read the LockWindowUpdate docs, no need to point out that it’s already there if it is.)
Insightful and good to know. Using the Community Content feature on MSDN, you ought to post links from the appropriate articles to here. Heck, I’m tempted to do it myself…
<i>(And if it isn’t meant for me, why post it onto my web site?)</i>
Because you actually read them and respond. You’re the face of a huge corporation, like it or not.
I have been known, recently even, to opine on the breadth of documentation required to properly teach a product. Raymond Chen made the same point in a recent post (emphasis mine, of course): I’m not sure if this series [of blog posts] was a succes ..
I’m one of the people who searched MSDN for a way to prevent a window from updating while doing something in the background and LockWindowUpdate was the first thing I found. I still think the documentation should be more clear though I understand your point of view on the subject. If you hadn’t written about it I would never have learned the proper way to lock a window from updating, so thanks.
Koro: CreateIC (though the documentation is kind of lame, look at CreateDC’s to figure out what to pass to all the fields).
AlmostAlive wrote:
"But the comments aren’t what you write, they’re for the community to discuss whatever they want about the topic."
imho that’s exactly wrong…this ain’t no democracy. The comments here are not for discussing anything other than whatever topic Raymond has raised. If he decided to enlighten us on the inner-workings of MSDN (right)…that’d be different.
And guess what…I wouldn’t be reading it.
Until then, please keep it on-topic…Raymond’s topic…so we can all learn about things which we already know aren’t cleared up by simply reading docs. Why do you think he does this in the first place?
Rock on, Raymond…I never learned so much actually useful info as I do here.
JD
"I’m not sure if this series was a success or not."
*Yesterday* googling for LockWindowUpdate had this blog as the *first* result. If that continues to hold, the series will continue to be a success and enlightening people on the issues of LockWindowUpdate for years to come.
I know arguing about function documentation isn’t something that you wanted everyone to do. It’s not part of your blog. But the comments aren’t what you write, they’re for the community to discuss whatever they want about the topic. After reading this last post on the matter, it seems even more *obvious* that the documentation is lacking. If using it in Vista is so horrible and alternatives exist then the documentation should say it. Not your problem, I agree. But you shouldn’t be taking blog comments so personally — nobody said *you* should be doing anything about it. Maybe we’ll get lucky and somebody else at Microsoft will read these comments.
"But, I’m Good Enough, I’m Smart Enough, and Doggone It, People Like Me!"
-Raymond Smalley
:)
>> I tried to keep the presentation light, but I guess my jokes fell flat, and people just used them as a springboard for negative comments.
I suspect and hope that the negative comments are from the few, whereas the appreciation of the many is largely silent. In common with all my cow-orkers who read your blog, I find your posts both enlightening and entertaining, but I’ve never thought it particularly pointful to post and say so.
Please don’t think that just because the comments tend to be a home for snark and pickiness, that that’s what most of your readers are actually thinking – after all, *commenters* are but a small proportion of *readers* …
"I’m not sure if this series was a success or not."
Raymond — not only are you tops for ‘lockwindowupdate’ in the major search engines — but the rest of the results (when they’re relevant) all give the BAD information about LockWindowUpdate (shudder — even a bunch of information on the Microsoft site).
You’ve done good, and thank you.
These series are always informative and interesting, so please keep them coming.
Maybe you need a new tagline: Instead of ‘not actually a .NET blog’ how about ‘I Did Not Write *All* Of Windows’?
Raymond: "the desktop window manager needs to compose all of the windows into an actual bitmap that it can give you when you call GetDCEx with the DCX_LOCKWINDOWUPDATE flag … desktop window manager does composition on the fly with the help of DirectX and accelerated video drivers."
LockWindowUpdate/DCX_LOCKWINDOWUPDATE isn’t the problem, it’s what people inevitably do *after* they’ve locked the screen — screen readback. When you read back from the screen, the DWM has to copy the bits back from video memory to a system memory bitmap (which is expensive for a number of reasons); the DWM never renders without DirectX+hardware acceleration. Screen readback can happen explicitly (e.g. using the screen DC as the source for a BitBlt) or implicitly (e.g. when the screen is the target for an AlphaBlend or PatBlt). These readback operations will be expensive whether or not LockWindowUpdate is used.
Also, it’s worth noting that UpdateLayeredWindow/SetLayeredWindowAttributes can only do straight up alpha blending and not any fancy ROPs, so if you *really* need to, say, R2_MERGEPENNOT with a yellow pen to the screen, then unfortunately there isn’t an alternative.
Using layered windows or region windows is ideal if you can use it instead.
Koro: "Does that mean that using GetDC(NULL) to get a temporary DC to call functions such as GetTextMetrics is a very wrong?"
No, GetDC(NULL) is fine to do. It’s only when readback happens that it becomes a problem.
@eikonos
‘I’m one of the people who searched MSDN for a way to prevent a window from updating while doing something in the background and LockWindowUpdate was the first thing I found.’
Me too. Though I probably looked on Google before MSDN. This series has been helpful, as I’ve found some of our code that is probably misusing LockWindowUpdate(). I don’t think I’d heard of SetWindowRedraw(), so without this series I wouldn’t have known any better. Good to hear that this information is top of the Google hit parade for LockWindowUpdate(), that ought to save others going down the wrong path.
As for the documentation, yes I was a bit surprised that LockWindowUpdate() didn’t do what I thought it did, and MSDN didn’t do anything to clear my confusion. Still, I find that MSDN is on the whole is remarkably good. It’s certainly better than Apple’s documentation IMO.
nikos: The term "regional windows" refers to the support exposed by the SetWindowRgn() API. It predates compositing effects like layered windows by some time – the feature was introduced in Windows NT 3.51 and Windows 95.
SetWindowRgn() adds a step to the clipping calculation for the visible region of your window (calculations the window manager already does to support partial or full occlusion). The simplest way to think of this is "non-rectangular" window support.
Complex clipping incurs a performance penalty on drawing operations, so care must be taken. Also, updating the region can have side-effects on invalid regions of your window and the windows under you, so unlike layered windows, you shouldn’t use regional windows for animation.
On the other hand, there is no backing store required so some simple non-animating effects are far cheaper to implement with regional windows.
As someone who highlighted problems with the documentation, I assume I’m one of the ‘negative’ posters various people are complaining about.
My view (apart from my opinion that I was trying to be constructive and positive) was that as Raymond’s blog is at least partially about compatibility issues in Windows, often caused by incorrect usages of APIs that then have to be supported, that problems with documentation that *cause* these errors was relevant. Particularly in the specific case of the function/API being discussed by Raymond.
Apparently that isn’t relevant after all, and documentation is something that happens to other people, so I apologise for the noise.
(As an aside, I did go and read the overviews on MSDN. There was more specific info on LockWindowUpdate, but still no clear indication that it should not be used for the purposes many people use it for – i.e. those purposes that might be assumed from its name. Also, I saw no mention of SetWindowRedraw() etc either. In fact, try searching MSDN for SetWindowRedraw() – even when you know the name of the function it’s not exactly easy to find.)
Oh well, whatever. After a period of hearing some people vehemently defend something (that most people agree is defective) from constructive suggestions that require small effort to implement, you kind of stop caring. That’s where I am now. It’s no wonder people misuse APIs.
Well, for one thing, you are someone we can complain to! Also, there is a chance for the readers to learn something as well!
The thing is, I think 95% of the people who complain know that they are doing something wrong, but they don’t want to admit that they are doing something wrong, and it becomes easy to blame MS.
I believe that the open source movements have an advantage that if I care to look, I can actually find out who wrote the documentation for a function and send my complains that way! Indeed, below all MAN pages, there is the author’s e-mail address, for good reason! MSDN would likely be a lot better if that where the case for all MSDN documentation as well. :) Of course, people move on, but within a year or so of being written, enough complains would be filed to get the documentation to a state better than that in which it started.
Excellent series, Raymond. Despite the fact that I lurk 99% of the time I felt the need to mention this as you seem to think the negative people are in something other than a pathetic minority.
Just ignore the complainers — eventually they’ll figure out how pathetic they are blaming $GIANT_CORP for their lack of programming skills.
@Devlin Bentley
You’re mising the subject of this entry. Please write that in some other forum.
The readers who actually learn something here should try to save Raymond to be able to expect from him to write more.
“And if it isn’t meant for me, why post it onto my web site?”
Like I said, a lot of posters assume that people who could act on it, MS insiders, can act on the comments.
Like it or not, your blog is under blogs.msdn and you allow comments. So, yes, it does give the impression that it is somewhat related to MSDN in general and people will comment on stuff you can’t change. We don’t know just how much power you have to effect changes.
Beside, even though your comments may change some people’s behavior, I doubt it will generally. I think it’s better to acknowledge this state of affair and only deal with what you can and not sweat it.
I agree that ‘the documentation sucks’ is not a novel contribution, but I thought I was saying a bit more than that – well, in fact, I was curious as to how much people like Raymond felt they were able to cause these things to be fixed (or not) – i.e. from the perspective of within MS.
As I mentioned, I’m fully aware that despite what some people may think, Raymond doesn’t wield some sort of superhuman power within MS. I also think that saying just because his blog is on the msdn blogs site that he is able to do stuff is not particularly valid. But then that may only be because I’ve been reading this blog for quite a while and I know what’s in Raymond’s power to change, and what is not.
To be super clear: I’m not moaning about this series. I’m very glad it’s here, so if I ever need to use LockWindowUpdate(), I’ve got some good pointers.
After all, Raymond’s series on shell extensions was the only way I ever worked out how to interface to Explorer to copy virtual files, etc. I’m not likely to start complaining about oldnewthing itself now :-)
Raymond, you’ve said in the past that you post entries in your blog at times so that other people in MS may see what they’re doing wrong. If you think it’s likely that other people at MS will read your posts, it should then be logical to assume that other people at MS will read the comments as well, and that these comments are directed at the same audience as the original posts. For that reason, it makes sense to assume they’re not directed at you unless they specifically say that they’re directed at you.
I’ve really enjoyed reading your blog, and have learned a lot from it. I’d hate for you to have to stop because you think people are bashing on you, especially if that’s not their intent.
I guess I’m weird, then, because I read the comments via RSS. Each post has its own feed, and my reader shows me those feeds. For example, the feed for this post is at
http://blogs.msdn.com/oldnewthing/commentrss.aspx?PostID=1747713
I don’t find it out of place that posts about things that people do wrong spark discussions about things that people do wrong or point out possible reasons that people do these things wrong and how to fix the problems that cause people to do things wrong. Private email, yes, that would be out of place, but not public discussion. I guess the big difference is whether one views blog comments as responses directly to the poster, or as public discussion.
Well I enjoyed it for one, and I suspect many other people who like peeking under the bonnet of Windows did too.
So ignore the negative posters and keep the geeky articles coming! :-)
James Bray
现在大家了解了LockWindowUpdate的设计æ„图，我现在将è¦å‘Šè¯‰å¤§å®¶ä½ 们为什么ä¸åº”当使用这个函数，甚至ä¸æ˜¯å› 为其设计æ„å›¾çš„ç¼˜å› ã€‚