{"id":95875,"date":"2017-03-31T07:00:00","date_gmt":"2017-03-31T21:00:00","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/oldnewthing\/?p=95875"},"modified":"2019-03-13T01:09:00","modified_gmt":"2019-03-13T08:09:00","slug":"20170331-00","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/oldnewthing\/20170331-00\/?p=95875","title":{"rendered":"A survey of the various ways of creating GDI bitmaps with predefined data"},"content":{"rendered":"

Suppose you have a buffer full of pixels and you want to create a GDI bitmap that contains those pixels. <\/p>\n

We’ll start with the Create­Bitmap<\/code> function<\/a>. This creates a device-dependent bitmap with the pixels you provide. The weird thing about this function is that it’s a device-dependent bitmap, but there’s no parameter that specifies the device! As a result, the bitmap has the format you specify, but you can select it only into device contexts that are compatible with the bitmap format. For example, if you create a 4bpp bitmap, then you can select it only into 4bpp device contexts.¹ <\/p>\n

Next up is the misleadingly-named Create­DI­Bitmap<\/code> function<\/a>. Even though the DI<\/i> stands for device independent, this function does not create a device-independent bitmap. It creates a device-dependent bitmap that is compatible with the provided device context. The reason it’s called DI<\/i> is that you can provide pixels in a device-independent format, and those pixels will be used to initialize the bitmap. As noted in the documentation, the behavior is functionally equivalent to Create­Compatible­Bitmap<\/code> followed by Set­DI­Bits<\/code>. <\/p>\n

If it’s a device-independent bitmap you want, then the function to use is Create­DIB­Section<\/code><\/a>. The simplest use of this function creates a device-independent bitmap and gives you a pointer to the in-memory pixel buffer. You can then manipulate the pixel buffer directly, say, by memcpy<\/code>ing the bytes from your original buffer. <\/p>\n

The fancier use of this function creates a device-independent bitmap around existing memory<\/i>. The memory needs to be in a file mapping object, either a file mapping object created from a file or (more often) a file mapping object created from the page file (in other words, a shared memory block). You can then specify the byte offset within the file mapping at which the pixel buffer starts. In this case, the memory is not copied; the memory in the file mapping object is the backing memory for the bitmap. If you modify the bitmap, then the contents of the file mapping object change; if you modify the contents of the file mapping object, you modify the bitmap. <\/p>\n

Here’s the table: <\/p>\n\n\n\n\n\n\n
Function<\/th>\nType of bitmap<\/th>\nResulting format<\/th>\nSource pixels<\/th>\nMust format match?<\/th>\n<\/tr>\n
Create­Bitmap<\/code><\/td>\nDevice-dependent<\/td>\nAs specified<\/td>\nCopied<\/td>\nYes<\/td>\n<\/tr>\n
Create­DI­Bitmap<\/code><\/td>\nDevice-dependent<\/td>\nDevice-compatible<\/td>\nCopied<\/td>\nNo<\/td>\n<\/tr>\n
Create­DIB­Section<\/code> without hSection<\/code><\/td>\nDevice-independent<\/td>\nAs specified<\/td>\nUninitialized (copy them yourself)<\/td>\nYes<\/td>\n<\/tr>\n
Create­DIB­Section<\/code> with hSection<\/code><\/td>\nDevice-independent<\/td>\nAs specified<\/td>\nShared<\/td>\nYes<\/td>\n<\/tr>\n<\/table>\n

In the above table, the Resulting format<\/i> column describes the pixel format of the returned bitmap. The Source pixels<\/i> column describes what happens to the pixels you pass as the source pixels: Are they copied into the bitmap, or does the bitmap share the memory with the source pixels? The Must format match?<\/i> column specifies whether the format of the source pixels must match the pixel format of the returned bitmap. If Must format match?<\/i> is No<\/i>, then the system will perform a format conversion. <\/p>\n

¹ Monochrome bitmaps are compatible with any device context and have special behavior when selected into color device contexts<\/a>.<\/p>\n","protected":false},"excerpt":{"rendered":"

So many to choose from.<\/p>\n","protected":false},"author":1069,"featured_media":111744,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[25],"class_list":["post-95875","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-oldnewthing","tag-code"],"acf":[],"blog_post_summary":"

So many to choose from.<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/95875","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/users\/1069"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/comments?post=95875"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/posts\/95875\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media\/111744"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/media?parent=95875"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/categories?post=95875"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/oldnewthing\/wp-json\/wp\/v2\/tags?post=95875"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}