TextureLoader.FromCubeFile(Device,String,Int32,Int32,Usage,Format,Pool,Filter,Filter,Int32,ImageInformation,PaletteEntry) Method (Microsoft.DirectX.Direct3D)

Article
06/30/2006

Creates a cube texture from a file.

Definition

Visual Basic Public Shared Function FromCubeFile( _
    ByVal device As Device, _
    ByVal srcFile As String, _
    ByVal size As Integer, _
    ByVal mipLevels As Integer, _
    ByVal usage As Usage, _
    ByVal format As Format, _
    ByVal pool As Pool, _
    ByVal filter As Filter, _
    ByVal mipFilter As Filter, _
    ByVal colorKey As Integer, _
    ByRef srcInformation As ImageInformation, _
    ByRef palette As PaletteEntry _
) As CubeTexture

C# public static CubeTexture FromCubeFile(
    Device device,
    string srcFile,
    int size,
    int mipLevels,
    Usage usage,
    Format format,
    Pool pool,
    Filter filter,
    Filter mipFilter,
    int colorKey,
    ref ImageInformation srcInformation,
    out PaletteEntry palette
);

C++ public:
static CubeTexture^ FromCubeFile(
    Device^ device,
    String^ srcFile,
    int size,
    int mipLevels,
    Usage usage,
    Format format,
    Pool pool,
    Filter filter,
    Filter mipFilter,
    int colorKey,
    ImageInformation% srcInformation,
    [Out] PaletteEntry% palette
);

JScript public static function FromCubeFile(
    device : Device,
    srcFile : String,
    size : int,
    mipLevels : int,
    usage : Usage,
    format : Format,
    pool : Pool,
    filter : Filter,
    mipFilter : Filter,
    colorKey : int,
    srcInformation : ImageInformation,
    palette : PaletteEntry
) : CubeTexture;

Parameters

device Microsoft.DirectX.Direct3D.Device
A Device object that represents the device to associate with the cube texture.

srcFile System.String
String that specifies the file name.

size System.Int32
Width and height of the cube texture, in pixels. For example, if the cube texture is an 8-pixel by 8-pixel cube, the value is 8. If the value is 0, the dimensions are taken from the file.

mipLevels System.Int32
Number of mip levels requested. If this value is 0, a complete mipmap chain is created.

usage Microsoft.DirectX.Direct3D.Usage
Zero or Usage.RenderTarget, or Usage.Dynamic. Setting this flag to Usage.RenderTarget indicates that the surface should be used as a render target. The resource can then be passed to the param_Surface_renderTarget parameter of the Device.SetRenderTarget method. If Usage.RenderTarget is specified, the application should determine whether the device supports this operation by calling Manager.CheckDeviceFormat. The Usage.Dynamic value indicates that the surface should be handled dynamically.

format Microsoft.DirectX.Direct3D.Format
Member of the Format enumerated type that describes the requested pixel format for the cube texture. The returned cube texture might have a different format from that specified by param_Format_format. Applications should check the format of the returned cube texture. If param_Format_format is Unknown, the format is taken from the file.

pool Microsoft.DirectX.Direct3D.Pool
Member of the Pool enumerated type that describes the memory class into which the cube texture should be placed.

filter Microsoft.DirectX.Direct3D.Filter
One or more Filter flags that control how the image is filtered.

mipFilter Microsoft.DirectX.Direct3D.Filter
One or more Filter flags that control how the mipmaps are filtered. In addition, use bits 27-31 to specify the number of mip levels to be skipped (from the top of the mipmap chain) when a .dds texture is loaded into memory; this allows you to skip up to 32 levels.

colorKey System.Int32
An Int32 value to replace with transparent black, or 0 to disable the color key. This value is always a 32-bit ARGB color that is independent of the source image format. Alpha is significant, and usually should be set to FF for opaque color keys. For example, for opaque black, the value equals 0xFF000000.

srcInformation Microsoft.DirectX.Direct3D.ImageInformation
[in, out] An ImageInformation structure to fill with a description of the data in the source image file, or 0.

palette Microsoft.DirectX.Direct3D.PaletteEntry[]
Array of PaletteEntry structures that represent a 256-color palette to fill in, or 0.

Return Value

Microsoft.DirectX.Direct3D.CubeTexture
A CubeTexture object that represents the created cube texture object.

Remarks

This method supports the following file formats: .bmp, .dds, .dib, .hdr, .jpg, .pfm, .png, .ppm, and .tga.

Cube textures differ from other surfaces in that they are collections of surfaces. To call Device.SetRenderTarget with a cube texture, select an individual face using CubeTexture.GetCubeMapSurface and pass the resulting surface to Device.SetRenderTarget.

The TextureLoader.FromCubeFile method uses the Microsoft DirectDraw surface (DDS) file format. The DXTex tool enables generation of a cube map from other file formats, and saves it as a .dds file.

Exceptions

InvalidCallException

The method call is invalid. For example, a method's parameter might contain an invalid value.

InvalidDataException

The data is invalid.

NotAvailableException

This device does not support the queried technique.

OutOfVideoMemoryException

Microsoft Direct3D does not have enough display memory to perform the operation.

OutOfMemoryException Leave Site

Direct3D could not allocate sufficient memory to complete the call.

Visual Basic	Public Shared Function FromCubeFile( _ ByVal device As Device, _ ByVal srcFile As String, _ ByVal size As Integer, _ ByVal mipLevels As Integer, _ ByVal usage As Usage, _ ByVal format As Format, _ ByVal pool As Pool, _ ByVal filter As Filter, _ ByVal mipFilter As Filter, _ ByVal colorKey As Integer, _ ByRef srcInformation As ImageInformation, _ ByRef palette As PaletteEntry _ ) As CubeTexture
C#	public static CubeTexture FromCubeFile( Device device, string srcFile, int size, int mipLevels, Usage usage, Format format, Pool pool, Filter filter, Filter mipFilter, int colorKey, ref ImageInformation srcInformation, out PaletteEntry palette );
C++	public: static CubeTexture^ FromCubeFile( Device^ device, String^ srcFile, int size, int mipLevels, Usage usage, Format format, Pool pool, Filter filter, Filter mipFilter, int colorKey, ImageInformation% srcInformation, [Out] PaletteEntry% palette );
JScript	public static function FromCubeFile( device : Device, srcFile : String, size : int, mipLevels : int, usage : Usage, format : Format, pool : Pool, filter : Filter, mipFilter : Filter, colorKey : int, srcInformation : ImageInformation, palette : PaletteEntry ) : CubeTexture;

device	Microsoft.DirectX.Direct3D.Device A Device object that represents the device to associate with the cube texture.
srcFile	System.String String that specifies the file name.
size	System.Int32 Width and height of the cube texture, in pixels. For example, if the cube texture is an 8-pixel by 8-pixel cube, the value is 8. If the value is 0, the dimensions are taken from the file.
mipLevels	System.Int32 Number of mip levels requested. If this value is 0, a complete mipmap chain is created.
usage	Microsoft.DirectX.Direct3D.Usage Zero or Usage.RenderTarget, or Usage.Dynamic. Setting this flag to Usage.RenderTarget indicates that the surface should be used as a render target. The resource can then be passed to the param_Surface_renderTarget parameter of the Device.SetRenderTarget method. If Usage.RenderTarget is specified, the application should determine whether the device supports this operation by calling Manager.CheckDeviceFormat. The Usage.Dynamic value indicates that the surface should be handled dynamically.
format	Microsoft.DirectX.Direct3D.Format Member of the Format enumerated type that describes the requested pixel format for the cube texture. The returned cube texture might have a different format from that specified by param_Format_format. Applications should check the format of the returned cube texture. If param_Format_format is Unknown, the format is taken from the file.
pool	Microsoft.DirectX.Direct3D.Pool Member of the Pool enumerated type that describes the memory class into which the cube texture should be placed.
filter	Microsoft.DirectX.Direct3D.Filter One or more Filter flags that control how the image is filtered.
mipFilter	Microsoft.DirectX.Direct3D.Filter One or more Filter flags that control how the mipmaps are filtered. In addition, use bits 27-31 to specify the number of mip levels to be skipped (from the top of the mipmap chain) when a .dds texture is loaded into memory; this allows you to skip up to 32 levels.
colorKey	System.Int32 An Int32 value to replace with transparent black, or 0 to disable the color key. This value is always a 32-bit ARGB color that is independent of the source image format. Alpha is significant, and usually should be set to FF for opaque color keys. For example, for opaque black, the value equals 0xFF000000.
srcInformation	Microsoft.DirectX.Direct3D.ImageInformation [in, out] An ImageInformation structure to fill with a description of the data in the source image file, or 0.
palette	Microsoft.DirectX.Direct3D.PaletteEntry[] Array of PaletteEntry structures that represent a 256-color palette to fill in, or 0.

TextureLoader.FromCubeFile(Device,String,Int32,Int32,Usage,Format,Pool,Filter,Filter,Int32,ImageInformation,PaletteEntry) Method (Microsoft.DirectX.Direct3D)

Additional resources