Class GorgonTexture2DView

A shader view for textures.

Inheritance
object
GorgonResourceView
GorgonShaderResourceView
GorgonTexture2DView
Implements
Inherited Members
Namespace: Gorgon.Graphics.Core
Assembly: Gorgon.Graphics.Core.dll
Syntax
public sealed class GorgonTexture2DView : GorgonShaderResourceView, IDisposable, IGorgonGraphicsObject, IEquatable<GorgonResourceView>, IEquatable<GorgonShaderResourceView>, IGorgonTexture2DInfo, IGorgonNamedObject, IGorgonImageInfo
Remarks

This is a texture shader view to allow a GorgonTexture2D to be bound to the GPU pipeline as a shader resource.

Use a resource view to allow a shader access to the contents of a resource (or sub resource). When the resource is created with a typeless format, this will allow the resource to be cast to any format within the same group.

Properties

| Edit this page View Source

ArrayCount

Property to return the number of array indices to use in the view.

Declaration
public int ArrayCount { get; }
Property Value
Type Description
int
Remarks

If the texture is a 2D texture cube, then this value will be a multiple of 6.

| Edit this page View Source

ArrayIndex

Property to return the first array index to use in the view.

Declaration
public int ArrayIndex { get; }
Property Value
Type Description
int
| Edit this page View Source

Binding

Property to return the flags to determine how the texture will be bound with the pipeline when rendering.

Declaration
public TextureBinding Binding { get; }
Property Value
Type Description
TextureBinding
| Edit this page View Source

Bounds

Property to return the bounding rectangle for the view.

Declaration
public Rectangle Bounds { get; }
Property Value
Type Description
Rectangle
Remarks

This value is the full bounding rectangle of the first mip map level for the texture associated with the view.

| Edit this page View Source

Format

Property to return the format for the view.

Declaration
public BufferFormat Format { get; }
Property Value
Type Description
BufferFormat
| Edit this page View Source

FormatInformation

Property to return information about the Format used by this view.

Declaration
public GorgonFormatInfo FormatInformation { get; }
Property Value
Type Description
GorgonFormatInfo
| Edit this page View Source

Height

Property to return the height of the texture in pixels.

Declaration
public int Height { get; }
Property Value
Type Description
int
Remarks

This value is the full height of the first mip map level for the texture associated with the view.

| Edit this page View Source

IsCubeMap

Property to return whether the texture is a texture cube or not.

Declaration
public bool IsCubeMap { get; }
Property Value
Type Description
bool
| Edit this page View Source

MipCount

Property to return the number of mip maps in the resource to view.

Declaration
public int MipCount { get; }
Property Value
Type Description
int
Remarks

If the texture is multisampled, then this value will be set to 1.

| Edit this page View Source

MipSlice

Property to return the index of the first mip map in the resource to view.

Declaration
public int MipSlice { get; }
Property Value
Type Description
int
Remarks

If the texture is multisampled, then this value will be set to 0.

| Edit this page View Source

MultisampleInfo

Property to return the multisample quality and count for the texture.

Declaration
public GorgonMultisampleInfo MultisampleInfo { get; }
Property Value
Type Description
GorgonMultisampleInfo
| Edit this page View Source

Shared

Property to return whether the resource used by this view can be shared or not.

Declaration
public TextureSharingOptions Shared { get; }
Property Value
Type Description
TextureSharingOptions
| Edit this page View Source

Texture

Property to return the texture that is bound to this view.

Declaration
public GorgonTexture2D Texture { get; }
Property Value
Type Description
GorgonTexture2D
| Edit this page View Source

Width

Property to return the width of the texture in pixels.

Declaration
public int Width { get; }
Property Value
Type Description
int
Remarks

This value is the full width of the first mip map level for the texture associated with the view.

Methods

| Edit this page View Source

CreateTexture(GorgonGraphics, IGorgonTexture2DInfo, IGorgonImage)

Function to create a new texture that is bindable to the GPU.

Declaration
public static GorgonTexture2DView CreateTexture(GorgonGraphics graphics, IGorgonTexture2DInfo info, IGorgonImage initialData = null)
Parameters
Type Name Description
GorgonGraphics graphics

The graphics interface to use when creating the target.
IGorgonTexture2DInfo info

The information about the texture.
IGorgonImage initialData

[Optional] Initial data used to populate the texture.
Returns
Type Description
GorgonTexture2DView

A new GorgonTexture2DView.
Remarks

This is a convenience method that will create a GorgonTexture2D and a GorgonTexture2DView as a single object that users can use to apply a texture as a shader resource. This helps simplify creation of a texture by executing some prerequisite steps on behalf of the user.

Since the GorgonTexture2D created by this method is linked to the GorgonTexture2DView returned, disposal of either one will dispose of the other on your behalf. If the user created a GorgonTexture2DView from the GetShaderResourceView(BufferFormat, int, int, int, int) method on the GorgonTexture2D, then it's assumed the user knows what they are doing and will handle the disposal of the texture and view on their own.

If an initialData image is provided, and the width/height/depth is not the same as the values in the info parameter, then the image data will be cropped to match the values in the info parameter. Things like array count, and mip levels will still be taken from the initialData image parameter.

Exceptions
Type Condition
ArgumentNullException

Thrown when the graphics, or info parameter is null.
See Also
| Edit this page View Source

Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

Declaration
public override void Dispose()
Overrides
| Edit this page View Source

FromFile(GorgonGraphics, string, IGorgonImageCodec, GorgonTexture2DLoadOptions)

Function to load a texture from a file.

Declaration
public static GorgonTexture2DView FromFile(GorgonGraphics graphics, string filePath, IGorgonImageCodec codec, GorgonTexture2DLoadOptions options = null)
Parameters
Type Name Description
GorgonGraphics graphics

The graphics interface that will own the texture.
string filePath

The path to the file.
IGorgonImageCodec codec

The codec that is used to decode the the data in the stream.
GorgonTexture2DLoadOptions options

[Optional] Options used to further define the texture.
Returns
Type Description
GorgonTexture2DView

A new GorgonTexture2DView
Remarks

This will load an IGorgonImage from a file on disk and put it into a GorgonTexture2D object and return a GorgonTexture2DView.

If specified, the optionsparameter will define how Gorgon and shaders should handle the texture. The GorgonTextureLoadOptions type contains the following:

  • BindingWhen defined, will indicate the TextureBinding that defines how the texture will be bound to the graphics pipeline. If it is omitted, then the binding will be ShaderResource.
  • UsageWhen defined, will indicate the preferred usage for the texture. If it is omitted, then the usage will be set to Default.
  • Multisample infoWhen defined (i.e. not null), defines the multisampling to apply to the texture. If omitted, then the default is NoMultiSampling.
  • ConvertToPremultipliedAlphaConverts the image to premultiplied alpha before uploading the image data to the texture.

Since the GorgonTexture2D created by this method is linked to the GorgonTexture2DView returned, disposal of either one will dispose of the other on your behalf. If the user created a GorgonTexture2DView from the GetShaderResourceView(BufferFormat, int, int, int, int) method on the GorgonTexture2D, then it's assumed the user knows what they are doing and will handle the disposal of the texture and view on their own.

Exceptions
Type Condition
ArgumentNullException

Thrown when the graphics, filePath, or the codec parameter is null.
ArgumentEmptyException

Thrown when the filePath parameter is empty.
| Edit this page View Source

FromStream(GorgonGraphics, Stream, IGorgonImageCodec, long?, GorgonTexture2DLoadOptions)

Function to load a texture from a Stream.

Declaration
public static GorgonTexture2DView FromStream(GorgonGraphics graphics, Stream stream, IGorgonImageCodec codec, long? size = null, GorgonTexture2DLoadOptions options = null)
Parameters
Type Name Description
GorgonGraphics graphics

The graphics interface that will own the texture.
Stream stream

The stream containing the texture image data.
IGorgonImageCodec codec

The codec that is used to decode the the data in the stream.
long? size

[Optional] The size of the image in the stream, in bytes.
GorgonTexture2DLoadOptions options

[Optional] Options used to further define the texture.
Returns
Type Description
GorgonTexture2DView

A new GorgonTexture2DView
Remarks

This will load an IGorgonImage from a stream and put it into a GorgonTexture2D object and return a GorgonTexture2DView.

If the size option is specified, then the method will read from the stream up to that number of bytes, so it is up to the user to provide an accurate size. If it is omitted then the stream length - stream position is used as the total size.

If specified, the optionsparameter will define how Gorgon and shaders should handle the texture. The GorgonTextureLoadOptions type contains the following:

  • BindingWhen defined, will indicate the TextureBinding that defines how the texture will be bound to the graphics pipeline. If it is omitted, then the binding will be ShaderResource.
  • UsageWhen defined, will indicate the preferred usage for the texture. If it is omitted, then the usage will be set to Default.
  • Multisample infoWhen defined (i.e. not null), defines the multisampling to apply to the texture. If omitted, then the default is NoMultiSampling.
  • ConvertToPremultipliedAlphaConverts the image to premultiplied alpha before uploading the image data to the texture.

Since the GorgonTexture2D created by this method is linked to the GorgonTexture2DView returned, disposal of either one will dispose of the other on your behalf. If the user created a GorgonTexture2DView from the GetShaderResourceView(BufferFormat, int, int, int, int) method on the GorgonTexture2D, then it's assumed the user knows what they are doing and will handle the disposal of the texture and view on their own.

Exceptions
Type Condition
ArgumentNullException

Thrown when the graphics, stream, or the codec parameter is null.
IOException

Thrown if the stream is write only.
EndOfStreamException

Thrown if reading the image would move beyond the end of the stream.
| Edit this page View Source

GetMipHeight(int)

Function to return the height of the texture at the current MipSlice in pixels.

Declaration
public int GetMipHeight(int mipLevel)
Parameters
Type Name Description
int mipLevel

The mip level to evaluate.
Returns
Type Description
int

The height of the mip map level assigned to MipSlice for the texture associated with the texture.
| Edit this page View Source

GetMipWidth(int)

Function to return the width of the texture at the current MipSlice in pixels.

Declaration
public int GetMipWidth(int mipLevel)
Parameters
Type Name Description
int mipLevel

The mip level to evaluate.
Returns
Type Description
int

The width of the mip map level assigned to MipSlice for the texture associated with the texture.
| Edit this page View Source

GetRenderTargetView(BufferFormat)

Function to create a new GorgonRenderTarget2DView for this texture.

Declaration
public GorgonRenderTarget2DView GetRenderTargetView(BufferFormat format = BufferFormat.Unknown)
Parameters
Type Name Description
BufferFormat format

[Optional] The format for the view.
Returns
Type Description
GorgonRenderTarget2DView

A GorgonTexture2DView used to bind the texture to a shader.
Remarks

This will create a view that allows a texture to become a render target. This allows rendering into texture data in a different format, or even a subsection of the texture.

The format parameter is used present the texture data as another format type to the shader. If this value is left at the default of Unknown, then the format from the this texture is used. The format must be castable to the format of this texture. If it is not, an exception will be thrown.

Exceptions
Type Condition
ArgumentException

Thrown when the format is typeless.
GorgonException

Thrown when this texture does not have a TextureBinding of RenderTarget.

-or-

Thrown when this texture has a Usage of Staging.
| Edit this page View Source

GetShaderResourceView(BufferFormat)

Function to create a new GorgonTexture2DView for this texture.

Declaration
public GorgonTexture2DView GetShaderResourceView(BufferFormat format = BufferFormat.Unknown)
Parameters
Type Name Description
BufferFormat format

[Optional] The format for the view.
Returns
Type Description
GorgonTexture2DView

A GorgonTexture2DView used to bind the texture to a shader.
Remarks

This will create a view that makes a texture accessible to shaders. This allows viewing of the texture data in a different format, or even a subsection of the texture from within the shader.

The format parameter is used present the texture data as another format type to the shader. If this value is left at the default of Unknown, then the format from the this texture is used. The format must be castable to the format of this texture. If it is not, an exception will be thrown.

Exceptions
Type Condition
ArgumentException

Thrown if the format is a typeless format.
GorgonException

Thrown when this texture does not have a TextureBinding of ShaderResource.

-or-

Thrown when this texture has a usage of Staging.

-or-

Thrown if the texture Format is not typeless, and the Binding is set to DepthStencil.
| Edit this page View Source

ToPixel(RectangleF, int?)

Function to convert a rectangle of texel coordinates to pixel space.

Declaration
public Rectangle ToPixel(RectangleF texelCoordinates, int? mipLevel = null)
Parameters
Type Name Description
RectangleF texelCoordinates

The texel coordinates to convert.
int? mipLevel

[Optional] The mip level to use.
Returns
Type Description
Rectangle

A rectangle containing the pixel space coordinates.
Remarks

If specified, the mipLevel only applies to the MipSlice and MipCount for this view, it will be constrained if it falls outside of that range. Because of this, the coordinates returned may not be the exact size of the texture bound to the view at mip level 0. If the mipLevel is omitted, then the first mip level for the underlying Texture is used.

| Edit this page View Source

ToPixel(Size2F, int?)

Function to convert a size value from texel coordinates to pixel space.

Declaration
public Size2 ToPixel(Size2F texelSize, int? mipLevel = null)
Parameters
Type Name Description
Size2F texelSize

The texel size to convert.
int? mipLevel

[Optional] The mip level to use.
Returns
Type Description
Size2

A size value containing the texel space coordinates.
Remarks

If specified, the mipLevel only applies to the MipSlice and MipCount for this view, it will be constrained if it falls outside of that range. Because of this, the coordinates returned may not be the exact size of the texture bound to the view at mip level 0. If the mipLevel is omitted, then the first mip level for the underlying Texture is used.

| Edit this page View Source

ToPixel(Vector2, int?)

Function to convert a 2D vector value from texel coordinates to pixel space.

Declaration
public Vector2 ToPixel(Vector2 texelVector, int? mipLevel = null)
Parameters
Type Name Description
Vector2 texelVector

The texel size to convert.
int? mipLevel

[Optional] The mip level to use.
Returns
Type Description
Vector2

A 2D vector containing the pixel space coordinates.
Remarks

If specified, the mipLevel only applies to the MipSlice and MipCount for this view, it will be constrained if it falls outside of that range. Because of this, the coordinates returned may not be the exact size of the texture bound to the view at mip level 0. If the mipLevel is omitted, then the first mip level for the underlying Texture is used.

| Edit this page View Source

ToTexel(Point, int?)

Function to convert a 2D point value from pixel coordinates to texel space.

Declaration
public Vector2 ToTexel(Point pixelPoint, int? mipLevel = null)
Parameters
Type Name Description
Point pixelPoint

The pixel size to convert.
int? mipLevel

[Optional] The mip level to use.
Returns
Type Description
Vector2

A 2D vector containing the texel space coordinates.
Remarks

If specified, the mipLevel only applies to the MipSlice and MipCount for this view, it will be constrained if it falls outside of that range. Because of this, the coordinates returned may not be the exact size of the texture bound to the view at mip level 0. If the mipLevel is omitted, then the first mip level for the underlying Texture is used.

| Edit this page View Source

ToTexel(Rectangle, int?)

Function to convert a rectangle of pixel coordinates to texel space.

Declaration
public RectangleF ToTexel(Rectangle pixelCoordinates, int? mipLevel = null)
Parameters
Type Name Description
Rectangle pixelCoordinates

The pixel coordinates to convert.
int? mipLevel

[Optional] The mip level to use.
Returns
Type Description
RectangleF

A rectangle containing the texel space coordinates.
Remarks

If specified, the mipLevel only applies to the MipSlice and MipCount for this view, it will be constrained if it falls outside of that range. Because of this, the coordinates returned may not be the exact size of the texture bound to the view at mip level 0. If the mipLevel is omitted, then the first mip level for the underlying Texture is used.

| Edit this page View Source

ToTexel(Size2, int?)

Function to convert a size value from pixel coordinates to texel space.

Declaration
public Size2F ToTexel(Size2 pixelSize, int? mipLevel = null)
Parameters
Type Name Description
Size2 pixelSize

The pixel size to convert.
int? mipLevel

[Optional] The mip level to use.
Returns
Type Description
Size2F

A size value containing the texel space coordinates.
Remarks

If specified, the mipLevel only applies to the MipSlice and MipCount for this view, it will be constrained if it falls outside of that range. Because of this, the coordinates returned may not be the exact size of the texture bound to the view at mip level 0. If the mipLevel is omitted, then the first mip level for the underlying Texture is used.

| Edit this page View Source

ToTexel(Vector2, int?)

Function to convert a 2D vector value from pixel coordinates to texel space.

Declaration
public Vector2 ToTexel(Vector2 pixelVector, int? mipLevel = null)
Parameters
Type Name Description
Vector2 pixelVector

The pixel size to convert.
int? mipLevel

[Optional] The mip level to use.
Returns
Type Description
Vector2

A 2D vector containing the texel space coordinates.
Remarks

If specified, the mipLevel only applies to the MipSlice and MipCount for this view, it will be constrained if it falls outside of that range. Because of this, the coordinates returned may not be the exact size of the texture bound to the view at mip level 0. If the mipLevel is omitted, then the first mip level for the underlying Texture is used.

Implements

Extension Methods