Technote 1182

QDErr NewGWorld     (GWorldPtr   *   offscreenGWorld,
                              short           pixelDepth,
                              const Rect  *   boundsRect,
                              CTabHandle      cTable,    /* can be NULL */
                              GDHandle        aGDevice,  /* can be NULL */
                              GWorldFlags     flags)
         

enum 
{
     pixPurge           = 1L << pixPurgeBit,
     noNewDevice        = 1L << noNewDeviceBit,
     useTempMem         = 1L << useTempMemBit,
     keepLocal          = 1L << keepLocalBit,
     useDistantHdwrMem  = 1L << useDistantHdwrMemBit,
     useLocalHdwrMem    = 1L << useLocalHdwrMemBit,
};
typedef unsigned longGWorldFlags;
         

rowBytes * (boundsRect.bottom - boundsRect.top)

リザルトコード

noErr	0		正常終了
paramErr	-50		不正なパラメータ
memFullErr	-108		メモリ不足によるエラー
cDepthErr	-157		無効な色数

『Inside Macintosh: Imaging With QuickDraw』も参照してください。 『Inside Macintosh: Imaging With QuickDraw』の 6-5 ページに記載されている Listing 6-1 と、6-10 ページに記載されている Listing 6-2 には、NewGWorld を使ってオフスクリーングラフィックスワールドを作成する方法が具体的に示されています。 オフスクリーングラフィックスワールドに対する色数、境界矩形、またはカラーテーブルを変更する必要がある場合は、『Inside Macintosh』の 6-23 ページに記載されている UpdateGWorld 関数を使用します。 ページの先頭に戻る 新しい NewGWorld () の使い方 新しい NewGWorld の使い方は基本的にこれまでと同様です。新しく追加された 2 つのフラグである useDistantHdwrMem および useLocalHdwrMem により、ユーザはオフスクリーンピクセルイメージが割り当てられる領域を指定できるようになりました。useDistantHdwrMem または useLocalHdwrMem を単独で使用すると、NewGWorld は、aGDevice で指定されているデバイス上の VRAM または AGP メモリ内のみにイメージを割り当てようとします。この割り当てに失敗すると、NewGWorld は異常終了し、memFullErr エラーを返します。useDistantHdwrMem と useLocalHdwrMem の両方を指定すると、NewGWorld はまず VRAM 内で割り当てを試み、この後、aGDevice で指定されているデバイスの AGP メモリ内で割り当てを試みます。両方の割り当てに失敗すると、NewGWorld は異常終了し、memFullErr エラーを返します。AGP メモリまたは VRAM 内で割り当てを行うときに、aGDevice には絶対に NULL を指定しないでください。NULL を指定すると、割り当てに使用するデバイスが不定になってしまいます (これはデベロッパによって意図されたことでないのは明らかです)。 useDistantHdwrMem は、一度 (または数回) 設定し、その後で繰り返し使用するピクセルイメージを割り当てるために役立ちます。システムメモリから VRAM ピクセルイメージへの書き込みには比較的時間がかかりますが、VRAM から VRAM、または VRAM からスクリーンへのハードウェアコピーは非常に高速に実行されます。現在のところ、コピーオペレーションがハードウェアアクセラレーションを使用するかどうかを判断するメカニズムは用意されていないため、VRAM 内に割り当てるピクセルイメージはすべて同じ色数を使用し、スクリーンと同じカラーテーブルを共有することが望ましいといえます。また、マスクやサイズ変更を使用しない単純なコピーオペレーションを使用し、できるかぎりコピーのパフォーマンスを向上できるように配慮してください。 useLocalHdwrMem は、AGP メモリ内でピクセルイメージの割り当てを試みます。システムに AGP グラフィックスシステムが搭載されていなかったり、NewGWorld がピクセルイメージを割り当てることができないと、割り当ては異常終了し、memFullErr エラーが返されます。AGP 割り当てはシステムメモリ内で実行されるため、VRAM 内に割り当てるピクセルイメージに関連するような問題の影響を受けることはありません。しかし、AGP メモリには、キャッシュに格納できない、他のシステムメモリとの間でコピーを行うと通常のシステムメモリよりも処理が若干遅くなるなど、いくつかの制限があります。それほど問題にはなりませんが、パフォーマンスが若干低下するのは事実です。 割り当てが行われる領域や、標準的なシステムメモリ以外の領域で割り当てを行うことに伴う一般的な注意事項 (前の段落で説明したような) を正しく理解することは非常に重要です。useDistantHdwrMem または useLocalHdwrMem フラグによるオフスクリーン GWorld を使用するときに、アプリケーションのパフォーマンスを向上させるポイントは、どのピクセルイメージが頻繁に使用されていて、どのピクセルイメージがハードウェアアクセラレーションによるコピーに移行できるかをきちんと認識することです。非常に頻繁に使用され、ほとんど変更されないイメージは、VRAM 内に置いてコピーのパフォーマンスを最適化することができます。一般的な用途には AGP メモリを使用できます。AGP メモリの容量は制限されていて、しかも OpenGL などの他のグラフィックサービスもこれを使用するため、より頻繁に使用されるイメージをまず割り当てるように注意を払います。また、AGP メモリは仮想メモリシステムによってディスクにスワップされず、使用可能な AGP メモリ容量はシステムにインストールされている物理メモリの容量によって変わる点にも注意する必要があります。 コピーにハードウェアアクセラレーションが使用されない場合、AGP メモリからスクリーンへのコピーのパフォーマンスは、最大でシステムメモリと同等になることが期待できます。同様にアクセラレーションが使用されないケースで、VRAM からスクリーンへのコピーのパフォーマンスはシステムメモリと比較すると若干遅くなります。このようにイメージを注意深く割り当て、AGP メモリと VRAM を賢く使い分けてください。 NewGWorld がアプリケーションヒープの外部 (つまり、AGP メモリ空間または VRAM) にメモリを割り当てるときは、アプリケーションを終了する前に DisposeGWorld を使って、そのメモリを適切に処理することが非常に重要です。これに失敗すると、メモリリークが発生し、それ以降 VRAM または AGP メモリを使用できなくなってしまいます。多くの場合、このようにしてリークしたメモリはシステムを再起動しないかぎり回復されません。 実際にインプリメントするときは、すでに述べた VRAM に割り当てる GWorld の注意事項を確実に守ってください。GWorld のピクセルイメージを VRAM 内で正しく移動またはパージすることが決め手です。これにより、VRAM GWorld を使用しようとするときに画面にゴミが表示されたり、無効なメモリにアクセスすることが確実になくなります。 ページの先頭に戻る インプリメントのサンプル NewGWorld のインプリメントは実際には非常に簡単です。以下に、実際の作業で役に立つ単純なサンプルコードを示します。まず、新しいフラグが使用できるかどうかをテストします。このとき必要になるのは、システムのバージョンを確認することだけです (NewGWorld の新バージョンに特殊なセレクタは含まれていないので)。使用中の Mac OS が 8.6 より大きいものであれば、useDistantHdwrMem および useLocalHdwrMem が使用可能であると見なせます。

Boolean gNewNewGWorld = false; long versionSystem; // これは、8.6 以降の Mac OS で動作する Gestalt ('sysv', &versionSystem); if (0x00000860 < (versionSystem & 0x00000FFFF)) gNewNewGWorld = true; // システムはバージョン 8.6 以降である

次に、GWorld の割り当てと再割り当てに必要となる関数をカプセル化する必要があります。両方の処理には同じロジックを使用します。つまり、まず GWorldPtr をチェックし、さらにピクセルイメージの baseAddr をチェックして、最後にウインドウの GDevice がまだオフスクリーンの GDevice と同じであるかどうかをチェックします。GWorld を割り当てるときは、位置入力パラメータを指定し、このパラメータを使って、割り当てを行うメモリ空間 (VRAM、AGP メモリ、またはアプリケーションヒープ) を決定します。割り当てが正常に終了しなかった場合は、次のタイプを対象に処理を繰り返します。もちろん、この動作は必要に応じて修正することができます。GWorld の割り当てまたは再割り当てが正常に終了したときは True が返され、既存の GWorld が有効なときは False が返されます。以下のサンプルコードはこの一連の処理を示しています。

Boolean BuildOffscreen (GWorldPtr * ppGWorld, WindowPtr pWindow, short * plocation) { GDHandle hgdWindow = NULL; Boolean fMustRebuild = false; if (NULL == *ppGWorld) // 渡された GWorld が割り当てられていない場合 fMustRebuild = true; else { PixMapHandle hPixmap = GetGWorldPixMap (*ppGWorld); // pixmap ハンドルが NULL であるか、pixmap のベースアドレスが NULL の場合 if ((NULL == hPixmap) || (!GetPixBaseAddr (hPixmap))) fMustRebuild = true; // GWorld がウインドウと同じデバイス上にない場合 else if (GetGWorldDevice(*ppGWorld) != GetWindowDevice (pWindow)) fMustRebuild = true; } if (fMustRebuild) // 再構築する必要がある { // ウインドウの色数 short wPixDepth = (**((CGrafPtr)pWindow)->portPixMap).pixelSize; GDHandle hgdWindow = GetWindowDevice (pWindow);// ウインドウの GDevice if (NULL != *ppGWorld) // 割り当てられた GWorld がある場合 { DisposeGWorld (*ppGWorld);// 現在の GWorld をダンプする *ppGWorld = NULL; } switch (*plocation) // 配置したい場所 { case kInVRAM: if (noErr == NewGWorld (ppGWorld, wPixDepth, &pWindow->portRect, NULL, hgdWindow, noNewDevice | useDistantHdwrMem)) break; // VRAM で失敗したら、そのシグナルを送り、AGP に移る SysBeep (30); *plocation = kInAGP; case kInAGP: if (noErr == NewGWorld (ppGWorld, wPixDepth, &pWindow->portRect, NULL, hgdWindow, noNewDevice | useLocalHdwrMem)) break; // AGP で失敗したら、そのシグナルを送り、システムメモリに移る SysBeep (30); *plocation = kInSystem; case kInSystem: default: if (noErr != NewGWorld (ppGWorld, wPixDepth, &pWindow->portRect, NULL, hgdWindow, keepLocal | noNewDevice)) { // システムでも失敗したら、GWorld を割り当てることはできない // 適切なロケーションがないことを示すシグナルを送り、デバッガに移る SysBeep (30); *plocation = kNoWhere; DebugStr ("\pUnable to allocate off screen image"); return false; // 何も割り当てられなかった } *plocation = kInSystem; } return true; // GWorld を再構築する } return false; // すべて OK }

この前の関数は、大多数のウインドウが常駐する GDevice を決定する GetWindowDevice を呼び出す点を除けば、標準的な Macintosh Toolbox 関数を使用しています。なお、ウインドウが複数のデバイスにわたるケースを処理するかどうかはそれぞれのアプリケーションデベロッパの判断に委ねられているということに注意してください。次に、GetWindowDevice のコードを示します。

GDHandle GetWindowDevice (WindowPtr pWindow) { Rect rectWind, rectSect; short wFrameHeight, wTitleHeight; long greatestArea, sectArea; GDHandle hgdNthDevice, hgdZoomOnThisDevice; rectWind = pWindow->portRect; LocalToGlobal ((Point*)& rectWind.top); // グローバル座標に変換する LocalToGlobal ((Point*)& rectWind.bottom); // ウインドウのタイトルバーの高さを計算する wFrameHeight = rectWind.left - 1 ? (**(((WindowPeek)pWindow)->strucRgn)).rgnBBox.left; wTitleHeight = rectWind.top - 1 ? (**(((WindowPeek)pWindow)->strucRgn)).rgnBBox.top; rectWind.top = rectWind.top - wTitleHeight; hgdNthDevice = GetDeviceList (); greatestArea = 0; // 0 に初期化する // GDevice リストに含まれるすべての gdRects に対するウインドウをチェックし、 // どの gdRect にウインドウの最大領域が含まれているかを記憶する while (hgdNthDevice) { if (TestDeviceAttribute (hgdNthDevice, screenDevice)) if (TestDeviceAttribute (hgdNthDevice, screenActive)) { // SectRect ルーチンはウインドウ矩形と // この GDevice 矩形との交差を計算し、 // 矩形同士が交わる場合は TRUE を返し、 // そうでない場合は FALSE を返す SectRect(&rectWind, &(**hgdNthDevice).gdRect, &rectSect); // まず、どのスクリーンが最大のウインドウ領域を保持しているかを // 判断し、現在のデバイス上での矩形の領域を計算する sectArea = (long)(rectSect.right - rectSect.left) * (rectSect.bottom - rectSect.top); if ( sectArea > greatestArea ) { greatestArea = sectArea;// いままでの最大の領域を設定する hgdZoomOnThisDevice = hgdNthDevice;// ズームデバイスを設定する } hgdNthDevice = GetNextDevice(hgdNthDevice); } } // while ループ return hgdZoomOnThisDevice; }

バッファの割り当てが完了した後は、それにデータを書き込み、それをウインドウにブリットするだけです。この処理を行うプロセスはこれまで同様です。次に、この処理の具体例を示します。なお、FillOffscreen は渡された GWorldPtr が有効であることを前提にしていますが、BlitToWindow はより一般的な用途に使用され、GWorld を対象とするチェックを実行します。

// オフスクリーンバッファをランダムな明色で塗りつぶす void FillOffscreen (GWorldPtr pGWorld) { GDHandle hGDSave; CGrafPtr pCGrafSave; Rect rectSource = (pGWorld->portRect); RGBColor rgbColor; rgbColor.red = (Random () + 32767) / 2 + 32767; rgbColor.green = (Random () + 32767) / 2 + 32767; rgbColor.blue = (Random () + 32767) / 2 + 32767; GetGWorld (&pCGrafSave, &hGDSave); SetGWorld (pGWorld, NULL); if (LockPixels (GetGWorldPixMap (pGWorld))) { // バックグランドを描画する EraseRect (&rectSource); RGBForeColor (&rgbColor); PaintRect (&rectSource); UnlockPixels (GetGWorldPixMap (pGWorld)); } SetGWorld (pCGrafSave, hGDSave); } // オフスクリーンをチェックし、それを前面にブリットする void BlitToWindow (GWorldPtr pGWorld, WindowPtr pWindow, short * pLocation) { Rect rectDest = ((GrafPtr)pWindow)->portRect; Rect rectSource = ((GrafPtr)pWindow)->portRect; GrafPtr pCGrafSave; // オフスクリーンが有効であることを確認し、必要な場合は再構築する if (BuildOffscreen (&pGWorld, pWindow, pLocation)) FillOffscreen (pGWorld); // ブリット GetPort (&pCGrafSave); SetPort ((GrafPtr) pWindow); if (LockPixels (GetGWorldPixMap (pGWorld))) { CopyBits (&((GrafPtr)pGWorld)->portBits, &pWindow->portBits, &rectSource, &rectDest, srcCopy, NULL); UnlockPixels (GetGWorldPixMap (pGWorld)); } SetPort (pCGrafSave); }

最後に、NewGWorld によって割り当てられたメモリが適切に処理されていることを確認する必要があります。次のコードはこの処理を具体的に示しています。

// GWorld がアプリケーションヒープ内に存在しない可能性があるため、この処理は非常に重要 if (pGWorld) DisposeGWorld (pGWorld); pGWorld = NULL;

ページの先頭に戻る

要約 新しい NewGWorld を使用すると、パフォーマンスオリエンティッドなアプリケーションを作成するときに使用できる選択肢の数が大幅に増加します。たとえば、ピクセルイメージを VRAM または AGP メモリ空間に割り当てることで、以前とは比べものにならないレベルのグラフィックスパフォーマンスを達成できます。ただし、これらの新機能を使用することでアプリケーションデベロッパにはいくつかの条件が課されることになり、コードがすべての条件下で適切に機能することを確認しなければならなくなります。以下に、新しい NewGWorld を使用するときに検討すべきチェックリストを示します。 システムのバージョンをチェックし、useDistantHdwrMem および useLocalHdwrMem フラグが使用可能であることを確認する。 seDistantHdwrMem または useLocalHdwrMem を使用するときは、GDevice を指定する。 エラーに対する戻り値をチェックする。 ピクセルイメージのベースアドレスを取得するときは、NULL であるかどうかをチェックする。 パージされたピクセルイメージを処理するための回復の仕組みをインプリメントする。 システムに時間を渡す関数や VRAM の割り当てと割り当て解除を行うことのできる関数の間でベースアドレスをキャッシュに格納しない。 GWorlds が適切に処理されていることを確認し、VRAM または AGP メモリでメモリリークが発生するのを防ぐ。 useDistantHdwrMem および useLocalHdwrMem フラグは、デベロッパにオフスクリーングラフィックスを処理するためのさまざまなオプションを提供しますが、アプリケーションに課される追加条件を十分に理解した上で使用する必要があります。

参考文献

アップルのテクニカルノートのwebサイト Inside Macintosh: Imaging With QuickDraw; Chapter 6: Offscreen Graphics Worlds

ページの先頭に戻る

更新日: 1999 年 10 月 5 日