GdiplusStartup API函数的介绍

GdiplusStartup(token, input, output)

The GdiplusStartup 作用是初始化GDI+函数库. CallGdiplusStartup before making any other GDI+ calls, and callGdiplusShutdown when you have finished using GDI+.

 

Status WINAPI GdiplusStartup(
    OUT ULONG_PTR *token,
    const GdiplusStartupInput *input,
    OUT GdiplusStartupOutput *output);

Parameters

token

[out] 第一个参数是指向一个32位的无符号整型的指针，也就是指向一个汇编中的DWORD变量的指针，用于接受GDI+的TOKEN.TOKEN可以暂时理解成一个句柄，就像窗口的句柄类似。这个参数在调用GdiplusShutdown的时候用到。这个函数在结束GDI+编程后调用，起作用是释放GDI+的资源。

input

[in] Pointer to a GdiplusStartupInput structure that contains the GDI+ version, a pointer to a debug callback function, a Boolean value that specifies whether to suppress the background thread, and a Boolean value that specifies whether to suppress external image codecs.

GdiplusStartupInput的定义如下：
struct GdiplusStartupInput
{
UINT32 GdiplusVersion;
DebugEventProc DebugEventCallback;
BOOL SuppressBackgroundThread;
BOOL SuppressExternalCodecs;

GdiplusStartupInput(
DebugEventProc debugEventCallback = NULL,
BOOL suppressBackgroundThread = FALSE,
BOOL suppressExternalCodecs = FALSE)
{
GdiplusVersion = 1;
DebugEventCallback = debugEventCallback;
SuppressBackgroundThread = suppressBackgroundThread;
SuppressExternalCodecs = suppressExternalCodecs;
}
};
这个定义看似复杂，实际就四个32位的变量，可以定义成如下的形式：
struct GdiplusStartupInput
{
UINT32 GdiplusVersion;
DebugEventProc DebugEventCallback;
BOOL SuppressBackgroundThread;
BOOL SuppressExternalCodecs;
}

output

[out] Pointer to a GdiplusStartupOutput structure that receives a pointer to a notification hook function and a pointer to a notification unhook function. If the SuppressBackgroundThread data member of the input parameter is FALSE, then this parameter can be NULL.

Return Values

If the function succeeds, it returns Ok, which is an element of the Status enumeration.

If the function fails, it returns one of the other elements of the Status enumeration.

Remarks

You must call GdiplusStartup before you create any GDI+ objects, and you must delete all of your GDI+ objects (or have them go out of scope) before you callGdiplusShutdown.

You can call GdiplusStartup on one thread and call GdiplusShutdown on another thread as long as you delete all of your GDI+ objects (or have them go out of scope) before you callGdiplusShutdown.

Do not call GdiplusStartup or GdiplusShutdown inDllMain or in any function that is called byDllMain. If you want to create a DLL that uses GDI+, you should use one of the following techniques to initialize GDI+:

• Require your clients to call GdiplusStartup before they call the functions in your DLL and to callGdiplusShutdown when they have finished using your DLL.
• Export your own startup function that calls GdiplusStartup and your own shutdown function that callsGdiplusShutdown. Require your clients to call your startup function before they call other functions in your DLL and to call your shutdown function when they have finished using your DLL.
• Call GdiplusStartup and GdiplusShutdown in each of your functions that make GDI+ calls.

Example Code [C++]

For an example of calling GdiplusStartup and GdiplusShutdown in a Windows application, seeGetting Started.

The following console application uses a GDI+ Image object to retrieve the width and height of a JPEG image. The code callsGdiplusStartup before creating theImage object and callsGdiplusShutdown before terminating. Note that theImage object is deleted before the call toGdiplusShutdown.

In the following code, the variable gdiplusStartupInput is initialized by the default constructor of theGdiplusStartupInput structure. The default constructor sets the data members of the structure to the following values:

• GdiplusVersion = 1
• DebugEventCallback = NULL
• SuppressBackgroundThread = FALSE
• SuppressExternalCodecs = FALSE

#include <windows.h>
#include <gdiplus.h>
#include <stdio.h>
using namespace Gdiplus;

INT main()
{
   GdiplusStartupInput gdiplusStartupInput;
   ULONG_PTR gdiplusToken;
   GdiplusStartup(&gdiplusToken, &gdiplusStartupInput, NULL);

   Image* image = new Image(L"FakePhoto.jpg");
   printf("The width of the image is %u./n", image->GetWidth());
   printf("The height of the image is %u./n", image->GetHeight()); 

   delete image;
   GdiplusShutdown(gdiplusToken);
   return 0;
}

Requirements

  Windows NT/2000/XP: Included in Windows XP and Windows .NET Server.
  Redistributable: Requires GDI+ on Windows NT 4.0 SP6; Windows 2000; and Windows 98/Me.
  Header: Declared in Gdiplusinit.h; include Gdiplus.h.
  Library: Use Gdiplus.lib. (!!!!!!!!!!!!!!!!记得在工程中加入此库，不然一大堆的报错)