GX2 Surface Copying, Resizing, Re-Formatting, etc.

Straight-up entire surface copy

See GX2CopySurface().

When to use GX2CopySurface()?

  • To do a 1:1 copy of an entire surface mipmap-level and slice. The image sizes and formats must match.
  • To swizzle or un-swizzle image data (aka swizzle conversion).
  • To tile or un-tile image data (aka tile conversion).
  • To copy any format, including block compressed (BC) or other non-color buffer formats.

When should GX2UT functions (GX2UTCopySurface(), GX2UTCopySurfaceRect(), or GX2UTSetAndCopySurface()) be used instead of GX2CopySurface()?

  • Using MSAA buffers - see GX2UTCopySurfaceRect()
  • Trying to stretch between surfaces of different sizes.
  • Trying to copy between surfaces of different formats.

What are the advantages and disadvantages of using GX2CopySurface()?

  • Advantages:
    • Optimized for GPU performance.
    • Future SDKs may provide bug fixes and performance improvements that your application may benefit from.
  • Disadvantages:
    • There is currently an above average CPU cost for calling this function to build the rendering commands (compared with other GX2 functions). If this function is going to be called frequently with the same arguments, then this CPU cost can be avoided by building a display list from the first GX2CopySurface() call and re-submitting that display list in place of subsequent GX2CopySurface() calls. CPU performance may be improved in later SDKs.
    • GX2CopySurface() makes no assumptions about the current GPU HW state and needs to configure many GPU registers before performing the copy. That is why if you are using state shadowing (which is recommended), you must call GX2SetContextState() after 1 or more calls to this (or similar) function(s) and before using other GX2 API calls.

GX2CopySurface() doesn't support copy between two surfaces with different formats or surface dimensions. If you need format conversion or size conversion, please switch to using the GX2UT GX2UTSetAndCopySurface() function instead of GX2CopySurface().

Sub-region surface copy

See GX2CopySurfaceEx()

This function is exactly like GX2CopySurface() except that it supports copying a number of sub-regions instead of the entire surface

When to use GX2CopySurfaceEx()?

  • To do a 1:1 copy of a sub-region of a mipmap-level and slice. The image formats must match.
  • To perform swizzle conversion or tile conversion.
  • To copy any format, including block compressed (BC) or other non-color buffer formats.

When should GX2UT functions (GX2UTCopySurfaceRect() or GX2UTSetAndCopySurfaceRect()) be used instead of GX2CopySurfaceEx()?

  • Using MSAA buffers
  • Trying to stretch the image (not a 1:1 copy).
  • Trying to copy between surfaces of different formats.

What are the advantages and disadvantages of using GX2CopySurfaceEx()?

Advanced flexible copy using GX2

GX2UT copy code (with source provided) gx2utCopy.cpp/.h:

GX2UTCopySurfaceRect( 
    const GX2Surface *srcSurface,
    u32 srcMip,
    u32 srcSlice,
    GX2UTRect *srcRect,
    GX2Surface *dstSurface,
    u32 dstMip,
    u32 dstSlice,
    GX2UTRect *dstRect,
    void* dstAuxPtr,
    u32 dstAuxSize)

Full source code is provided, so you can use it in your game and make any modification you want.

When to use GX2UT functions or source code?

  • Anytime, as long as the source and destination surfaces are not block compressed (BC) formats.
  • To swizzle or un-swizzle image data (aka swizzle conversion).
  • To tile or un-tile image data (aka tile conversion).
  • To copy to and from MSAA buffers.
  • To perform arbitrary stretching between surfaces of different sizes or to do stretching of sub-regions.
  • To copy between surfaces of different formats.
  • To use different image filtering than bi-linear.

When should GX2CopySurface() be used instead of GX2UTCopySurface* functions?

What are the advantages and disadvantages of using GX2UTCopySurface* functions()?

  • Advantages:
    • Full source code is provided for easy integration into your application. You can easily change the code to alter its behavior.
    • Lower CPU overhead than calling GX2CopySurface().
    • You have full control over state management.
      • If you want to disable state shadowing, change state before the copy, and restore a state context after the copy, you can do that.
      • If you want to create a separate state context just for copies, load that state context before each copy, and then restore a state context after the copy, you can do that.
      • If you want to track the render state used in your application, just change the few render states needed for the copy to work, and then restore those render states after the copy, you can do that.
  • Disadvantages:
    • Calling GX2UTCopySurface* changes the render state in the application's context (and state shadow). The programmer is responsible for restoring/undoing any render state changes made by GX2UT code (which is easily done by disabling state shadowing before the copy and restoring the state context after the call).
    • It currently is not as fast on the GPU as calling GX2CopySurface() but this is likely to change in future SDKs. The performance difference is less than 5%.

CONFIDENTIAL