documentation.xml

<?xml version="1.0" encoding="utf-8" ?> 
<GameLib>
  <Common>
    <Dispose>
      <summary>Releases unmanaged resources used by the object.</summary>
    </Dispose>
    <Finalizer>
      <summary>Releases unmanaged resources used by the object.</summary>
    </Finalizer>
  </Common>
  
  <IComparable>
    <CompareTo>
      <summary>Compares the current instance with another object of the same type.</summary>
      <param name="obj">An object to compare with this instance.</param>
      <returns>An integer that indicates the relative order of the comparands. The return value has these meanings:
      <list type="table">
      <listheader><term>Value</term><description>Meaning</description></listheader>
      <item><term>Less than zero</term><description>This instance is less than <paramref name="obj"/>.</description></item>
      <item><term>Zero</term><description>This instance is equal to <paramref name="obj"/>.</description></item>
      <item><term>Greater than zero</term><description>This instance is greater than <paramref name="obj"/>.</description></item>
      </list>
      </returns>
    </CompareTo>
  </IComparable>

  <IConvertible>
    <ToUInt64>
      <summary>Converts this value to a <see cref="UInt64"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>A <see cref="UInt64"/> representing this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToUInt64>
    <ToSByte>
      <summary>Converts this value to an <see cref="SByte"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>An <see cref="SByte"/> representing this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToSByte>
    <ToDouble>
      <summary>Converts this value to a <see cref="Double"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>The <see cref="Double"/> closest to this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToDouble>
    <ToSingle>
      <summary>Converts this value to a <see cref="Single"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>The <see cref="Single"/> closest to this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToSingle>
    <ToInt32>
      <summary>Converts this value to an <see cref="Int32"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>An <see cref="Int32"/> representing this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToInt32>
    <ToUInt16>
      <summary>Converts this value to a <see cref="UInt16"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>A <see cref="UInt16"/> representing this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToUInt16>
    <ToInt16>
      <summary>Converts this value to an <see cref="Int16"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>An <see cref="Int16"/> representing this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToInt16>
    <ToString>
      <summary>Converts this value to a string.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>An string representing this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToString>
    <ToByte>
      <summary>Converts this value to a <see cref="Byte"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>An <see cref="Byte"/> representing this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToByte>
    <ToChar>
      <summary>Converts this value to a <see cref="Char"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>An <see cref="Char"/> representing this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToChar>
    <ToInt64>
      <summary>Converts this value to an <see cref="Int64"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>An <see cref="Int64"/> representing this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToInt64>
    <ToDecimal>
      <summary>Converts this value to a <see cref="Decimal"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>A <see cref="Decimal"/> representing this value.</returns>
    </ToDecimal>
    <ToType>
      <summary>Converts the value to the given type.</summary>
      <param name="conversionType">The type to which this value should be converted.</param>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>An object containing this value converted to the given type.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
      <exception cref="InvalidCastException">Thrown if no conversion to the destination type exists.</exception>
    </ToType>
    <ToUInt32>
      <summary>Converts this value to a <see cref="UInt32"/>.</summary>
      <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
      <returns>A <see cref="UInt32"/> representing this value.</returns>
      <exception cref="OverflowException">Thrown if the value cannot be represented by the return type.</exception>
    </ToUInt32>
  </IConvertible>

  <Color>
    <HCL>
      <remarks>
        <para>
          The HCL (hue-chroma-luma) color model is, like HSL (hue-saturation-lightness) and HSV (hue-saturation-value), a
          transformation of the RGB color space in an attempt to provide more perceptually relevant dimensions. In the HSL and
          HSV systems, changing one component causes substantial changes in the others as well.
          For instance, altering the hue causes a change in perceived saturation and brightness. These changes are
          nonlinear and can go in either direction, making them difficult to intuitively predict. The HCL model, however,
          achieves greater perceived independence between its dimensions, allowing one component to be adjusted with fewer
          perceived changes to the others. Its dimensions are also more perceptually relevant, with the luma value being much
          better correlated with actual perceived lightness than either HSL's lightness or HSV's value. For these reasons, it
          is better for color blending and image adjustment, and is used by <see cref="BlendMode.Hue" />,
          <see cref="BlendMode.Chroma" />, <see cref="BlendMode.Luma" />, and <see cref="BlendMode.Color" />.
        </para>
        <para>
          However, it does not map one-to-one with the RGB model. All RGB colors can be represented as HCL colors, but there
          are many HCL colors that cannot be represented in RGB. This complicates its use in certain applications. Like
          HSL and HSV, and RGB generally, HCL is device-dependent, and does not describe actual colors, only the relative
          intensities of whatever RGB primaries the display device uses.
        </para>
      </remarks>
    </HCL>
    <HSLHSV>
      <para>
        HSL (hue-saturation-lightness) and HSV (hue-saturation-value, also known as HSB [hue-saturation-brightness]) are two
        quite similar color models that represent a
        transformation of the RGB color space into ones that provide more perceptually relevant dimensions. In both models,
        the RGB cube is transformed into a cylinder with hue being the circular angle (with red at 0 degrees, green at 120
        degrees, and blue at 240 degrees), and lightness (or value) increasing from 0 at the bottom to 1 at the top. If you
        consider a line passing vertically through the center, both systems represent saturation as the (shortest) distance from
        a color point to the line, and the line itself passes through the gray colors (from black to white). Both systems also
        place the pure colors around the outside edge of a circular slice of the cylinder. The difference is that HSL places the
        pure colors in the vertical center of the cylinder (i.e. they have a lightness of 0.5), while HSV places them at the top
        (i.e. they have a value of 1).
      </para>
      <para>
        Both systems map one-to-one with RGB, so any HSL or HSV color is a valid RGB color, and vice-versa. This makes their use
        straightforward in color pickers and other applications where out-of-gamut colors would be troublesome. Because of their
        many similarities, it may be difficult to choose between HSL and HSV. Typically, HSL does a better job of representing
        brightness, while HSV does a better job of representing saturation. However neither does the job particularly well, as
        both have substantial perceived dependencies among their components. Changing hue, for instance, causes changes in
        perceived saturation and brightness, and the changes are non-linear and difficult to predict. This makes both systems
        poor for image adjustment applications, as it is impossible to adjust a single component without producing apparent
        changes in the others. HCL is a better choice for image adjustment, but its chroma component is less intuitive than the
        saturation components of HSL and HSV, making it a poorer choice for color pickers and similar applications.
        Like RGB generally, HSL and HSV are device-dependent, and do not describe actual colors,
        only the relative intensities of whatever RGB primaries the display device uses.
      </para>
    </HSLHSV>
  </Color>

  <Fonts>
    <LineHeight>
      <summary>Gets the vertical offset that should be added to move the draw position to the next line. This is
        equivalent to the height of the font plus spacing between lines.
      </summary>
    </LineHeight>

    <CalculateSize>
      <summary>Calculates the size of a string of text.</summary>
      <param name="text">The text to use for the calculation.</param>
      <returns>A <see cref="Size"/> that contains the amount of space required to render the given text with this
        font.
      </returns>
      <remarks>This method does not perform word-wrapping on the text, and returns a calculation assuming the text
        is rendered as a single line.
      </remarks>
    </CalculateSize>

    <HowManyFit>
      <summary>Calculates how many characters of the given string would fit into the given width.</summary>
      <param name="text">The string to test.</param>
      <param name="width">The available width, in pixels.</param>
      <returns>The number of characters that would fully fit within the given width.</returns>
    </HowManyFit>

    <OnDisplayFormatChanged>
      <summary>This method is called when the video mode changes.</summary>
      <remarks>
        If it's important to know when the video mode changes, override this method. Remember to call
        the base class' implementation as well. This might be used to convert font images to a format suitable for
        fast blitting to the screen, for instance.
      </remarks>
    </OnDisplayFormatChanged>
    
    <Render>
      <Point>
        <Common>
          <summary>Renders text at a given point.</summary>
          <param name="dest">The surface to render into.</param>
          <param name="text">The text to render.</param>
          <returns>Returns the width of the text rendered plus spacing so that you can use the value to calculate where
          more text can be rendered (by adding the returned width to the starting position).
          </returns>
        </Common>
        <Pt>
          <!--<include file="documentation.xml" path="//Fonts/Render/Point/Common/*"/>-->
          <param name="pt">The point where the top-left corner of the rendered text should appear.</param>
        </Pt>
        <XY>
          <!--<include file="documentation.xml" path="//Fonts/Render/Point/Common/*"/>-->
          <param name="x">The X coordinate where the left side of the rendered text should appear.</param>
          <param name="y">The Y coordinate where the top edge of the rendered text should appear.</param>
        </XY>
      </Point>
      
      <Rect>
        <Common>
          <summary>Word-wraps and renders text into a given rectangle.</summary>
          <param name="dest">The surface to render into.</param>
          <param name="text">The text to render.</param>
          <param name="rect">The area into which text will be rendered.</param>
        </Common>
        <Align>
          <!--<include file="documentation.xml" path="//Fonts/Render/Rect/Common/*"/>-->
          <param name="align">The <see cref="ContentAlignment"/> to use inside the rectangle.</param>
          <returns>Returns the end point of the rendering, where rendering can be continue with more text.
          This only works with top-left alignment, since the endpoints for other types of alignment require before-hand
          knowledge of the amount of text. For other alignment types, the value of the returned point is undefined.
          </returns>
        </Align>
        <NoAlign>
          <!--<include file="documentation.xml" path="//Fonts/Render/Rect/Common/*"/>-->
          <returns>Returns the end point of the rendering, where rendering can be continue with more text.</returns>
        </NoAlign>
        <Offset>
          <param name="startx">The X offset into the rectangle at which rendering will begin.</param>
          <param name="starty">The Y offset into the rectangle at which rendering will begin.</param>
        </Offset>
      </Rect>
    </Render>
    
    <WordWrap>
      <Common>
        <summary>Word-wraps text into a specified area.</summary>
        <param name="text">The text to word-wrap.</param>
        <returns>An array of integers specifying indices into the string. There is one element for each line of text.
          The value of the element is how many characters should be rendered on that line.
        </returns>
        <remarks>Currently, a newline character will not force a line break. This behavior will be changed in the
          future.
        </remarks>
      </Common>
      <Size>
        <!--<include file="documentation.xml" path="//Fonts/WordWrap/Common/*"/>-->
        <param name="size">The size of the area bounding the text.</param>
      </Size>
      <Rect>
        <!--<include file="documentation.xml" path="//Fonts/WordWrap/Common/*"/>-->
        <param name="rect">The area bounding the text.</param>
      </Rect>
      <Dims>
        <!--<include file="documentation.xml" path="//Fonts/WordWrap/Common/*"/>-->
        <param name="width">The width of the area bounding the text.</param>
        <param name="height">The height of the area bounding the text.</param>
      </Dims>
      <Offset>
        <param name="startx">The X offset into the rectangle at which the text should start.</param>
        <param name="starty">The Y offset into the rectangle at which the text should start.</param>
      </Offset>
      <Breakers>
        <param name="breakers">An array of characters that will be used to break the text. Those characters will
          mark preferred places within the string to break to a new line.
        </param>
      </Breakers>
    </WordWrap>

    <BitmapFont>
      <Common>
        <param name="font">A surface containing the font data.</param>
        <param name="charset">A list of characters in the font, in the order in which they appear in the image.
        The font class can operate much more efficiently if the characters in the character set are contiguous.
        That is, for each each character, its value is one greater than value of the previous character.
        </param>
      </Common>
      <BitmapFont1>
        <!--<include file="documentation.xml" path="//Fonts/BitmapFont/Common/*"/>-->
        <param name="charWidth">The width of the characters in the font.</param>
        <remarks>The surface should contain all the characters, in the order specified by <paramref name="charset"/>,
        all in a single row. Each character should be <paramref name="charWidth"/> pixels wide, and there should be no
        unused space anywhere. If the surface has a color key or alpha channel, it will be used.
        </remarks>
      </BitmapFont1>
      <BitmapFont2>
        <!--<include file="documentation.xml" path="//Fonts/BitmapFont/Common/*"/>-->
        <param name="charWidths">An array the same length as <paramref name="charset"/>, containing the width of each
        character.
        </param>
        <remarks>The surface should contain all the characters, in the order specified by <paramref name="charset"/>,
        all in a single row. Each character should the number of pixels specified in <paramref name="charWidths"/>
        pixels wide, and there should be no unused space anywhere. If the surface has a color key or alpha channel,
        it will be used.
        </remarks>
      </BitmapFont2>
    </BitmapFont>
    
    <TrueTypeFont>
      <Cons>
        <Stream>
          <summary>Initializes this font from a stream containing TrueType font data.</summary>
          <param name="stream">The stream to read the font from. The stream must be seekable, with its entire set of
          data devoted to the font.
          </param>
          <param name="pointSize">The size of the font, in points (based on 72dpi).</param>
        </Stream>
        <File>
          <summary>Initializes this font from a file on disk.</summary>
          <param name="filename">The path to the TrueType font file.</param>
          <param name="pointSize">The size of the font, in points (based on 72dpi).</param>
        </File>
        <Index>
          <param name="fontIndex">Some fonts contain multiple faces. This parameter selects which face to use
            (zero-based).
          </param>
        </Index>
        <AutoClose>
          <param name="autoClose">If true, the stream will be closed after the font is loaded.</param>
        </AutoClose>
        <WillClose>
          <remarks>The stream will be closed after the font is loaded.</remarks>
        </WillClose>
      </Cons>
    </TrueTypeFont>
 </Fonts>

 <Mathematics>
  <Fixed>
   <ToDateTime>
    <summary>Throws <see cref="InvalidCastException"/> because there's no sensible conversion to
    <see cref="DateTime"/>
    </summary>
    <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
    <returns>Doesn't return.</returns>
    <exception cref="InvalidCastException">Always thrown.</exception>
   </ToDateTime>
   <ToBoolean>
    <summary>Converts this value to a <see cref="Boolean"/>.</summary>
    <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
    <returns>A <see cref="Boolean"/> that will be false if the value is zero and true otherwise.</returns>
   </ToBoolean>
   <ToString1>
    <summary>Converts this fixed-point number into a string.</summary>
    <param name="format">A format code which controls the conversion to string.</param>
    <returns>A string representing this fixed-point number.</returns>
    <remarks>See <see cref="Double.ToString(string)"/> for information on the available formatting codes.</remarks>
   </ToString1>
   <ToString2>
    <summary>Converts this fixed-point number into a string.</summary>
    <param name="format">A format code which controls the conversion to string.</param>
    <param name="provider">An <see cref="IFormatProvider"/> used to control formatting, or null to use the default.</param>
    <returns>A string representing this fixed-point number.</returns>
    <remarks>See <see cref="Double.ToString(string)"/> for information on the available formatting codes.</remarks>
   </ToString2>
  </Fixed>
 </Mathematics>

 <Network>
  <Common>
    <IsConnected>
      <summary>Returns true if the connection is open.</summary>
      <remarks>Note that this property may return true even if the connection has been broken. This method simply
      returns the connection state that existed when the most recent I/O operation was performed.
      </remarks>
    </IsConnected>
    <GetQueueStatus>
      <summary>Gets information about the status of the receive and/or send queues.</summary>
      <param name="flags">A set of <see cref="QueueStatusFlag"/> flags that determine what data will be returned.</param>
      <returns>A <see cref="QueueStatus"/> structure containing the number and total size of messages waiting in
      the queues specified by <paramref name="flags"/>.
      </returns>
    </GetQueueStatus>
    <LagAverage>
      <summary>Gets or sets the average amount of lag in milliseconds.</summary>
      <remarks>This property can be used to help simulate unfavorable network conditions.</remarks>
    </LagAverage>
    <LagVariance>
      <summary>Gets or sets the amount that the lag varies from <see cref="LagAverage"/>, in milliseconds.</summary>
      <remarks>This property can be used to help simulate unfavorable network conditions.</remarks>
    </LagVariance>
  </Common>
  
  <Client>
    <Send>
      <Common>
        <summary>Queues a message for sending.</summary>
      </Common>
      <byteData><param name="data">An array of <see cref="System.Byte"/> containing the message data.</param></byteData>
      <Index>
        <param name="index">The index into <paramref name="data"/> at which the message data begins.</param>
        <param name="length">The length of the message data.</param>
      </Index>
      <Flags>
        <param name="flags">A set of <see cref="SendFlag"/> values that will be used to control how the message is sent.</param>
      </Flags>
      <objData>
        <param name="data">An object representing the message data. It will be automatically serialized, so its type
        must have been registered with the <see cref="MessageConverter"/>.
        </param>
      </objData>
      <Timeout>
        <param name="timeoutMs">A timeout value, in milliseconds, indicating when the message will expire. If the
        message hasn't been sent over the network before the timeout expires, the message will be dropped. A timeout
        value of zero indicates that the message will not expire.
        </param>
      </Timeout>
    </Send>
  </Client>

  <MessageConverter>
    <RegisterType>
      <remarks>
      <para>Registering a type allows it to be serialized and deserialized very efficiently. To achieve this
      efficiency, certain restrictions are placed upon the types that can be registered. However, for each
      restriction, there is a way to alleviate the restriction, so in effect, almost any type you create can be
      serialized.
      </para>
      <para>The primary restriction is that the type must be blittable. A blittable type is essentially a type
      that contains no references and has a predetermined memory layout. A value type (structure) that contains
      only blittable fields has a predetermined memory layout, as do all primitive types. A class can also have
      a predetermined memory layout if the <see cref="System.Runtime.InteropServices.StructLayoutAttribute"/>
      attribute is applied to it.
      </para>
      <para>Arrays of blittable types are also considered to be blittable. However, you should not register the
      array type directly. For any type that can be serialized, arrays of that type can also be serialized
      automatically. Simply register the element type of the array. So if you want to serialize an array of
      <see cref="System.DateTime"/>, simply register the <see cref="System.DateTime"/> class.
      However, note that serialization of arrays with more than one dimension is not supported.
      </para>
      <para>You can serialize non-blittable types and multi-dimensional arrays in one of two ways. First, you can
      use the <see cref="System.Runtime.InteropServices.MarshalAsAttribute">MarshalAs</see> attribute to convert
      non-blittable fields to blittable types. Or, you can use the <see cref="INetSerializable"/> interface.
      Any type that implements the <see cref="INetSerializable"/> interface can be serialized by this code.
      However, for deserialization, an object implementing that interface must provide a default constructor
      (that is, a constructor that takes no arguments).
      </para>
      <para>If you are using multiple instances of the <see cref="MessageConverter"/> class, (for instance, one for
      serialization and one for deserialization), all instances must have the same types registered in the same
      order or else the behavior is undefined. (At best, an exception will be thrown during deserialization, but
      that cannot be relied upon. Data corruption or crashes may result.)
      </para>
      <para>One final note. For types that do not implement <see cref="INetSerializable"/>, an attempt will be made
      to determine whether the type is blittable or not. This process uses reflection and so the code needs to have
      permission to reflect on types.
      </para>
      </remarks>
    </RegisterType>
  </MessageConverter>

  <NetLink>
    <Send>
      <Common>
        <summary>Queues a message for sending.</summary>
        <param name="data">An array of <see cref="System.Byte"/> containing the message data.</param>
      </Common>
      <Index>
        <param name="index">The index into <paramref name="data"/> at which the message data begins.</param>
        <param name="length">The length of the message data.</param>
      </Index>
      <Stream>
        <param name="attachedStream">
          A stream that will be attached to the message, or null. The stream will be closed after it has been sent.
        </param>
      </Stream>
      <Flags>
        <param name="flags">A set of <see cref="SendFlag"/> values that will be used to control how the message is sent.</param>
      </Flags>
      <Timeout>
        <param name="timeoutMs">A timeout value, in milliseconds, indicating when the message will expire. If the
        message hasn't been sent over the network before the timeout expires, the message will be dropped. A timeout
        value of zero indicates that the message will not expire. <see cref="NoTimeout"/> cannot be used with this
        parameter.
        </param>
      </Timeout>
      <Tag>
        <param name="tag">A value that will be associated with the message. The tag value can be retrieved using the
        <see cref="LinkMessage.Tag"/> property.
        </param>
      </Tag>
    </Send>
  </NetLink>
  
  <Server>
    <Send>
      <Common>
        <summary>Queues a message for sending.</summary>
      </Common>
      <CommonToAll>
        <summary>Queues a message for sending to all players.</summary>
      </CommonToAll>
      <CommonToAllExcept>
        <summary>Queues a message for sending to all players except the given player.</summary>
      </CommonToAllExcept>
      <ToPlayer>
        <param name="toWhom">The addressee of the message. An exception will be thrown if the player has been dropped.</param>
      </ToPlayer>
      <ToList>
        <param name="toWhom">
          A collection of addressee of the message. The message will be sent to all players in the
          collection. An exception will be thrown if any players have been dropped.
        </param>
      </ToList>
      <byteData><param name="data">An array of <see cref="System.Byte"/> containing the message data.</param></byteData>
      <Index>
        <param name="index">The index into <paramref name="data"/> at which the message data begins.</param>
        <param name="length">The length of the message data.</param>
      </Index>
      <Flags>
        <param name="flags">A set of <see cref="SendFlag"/> values that will be used to control how the message is sent.</param>
      </Flags>
      <objData>
        <param name="data">An object representing the message data. It will be automatically serialized, so its type
        must have been registered with the <see cref="MessageConverter"/>.
        </param>
      </objData>
      <Timeout>
        <param name="timeoutMs">A timeout value, in milliseconds, indicating when the message will expire. If the
        message hasn't been sent over the network before the timeout expires, the message will be dropped. A timeout
        value of zero indicates that the message will not expire.
        </param>
      </Timeout>
    </Send>
  </Server>
 </Network>

 <Video>
  <OpenGL>
   <TexImage2D>
    <summary>Uploads a surface to video memory as a 2d texture.</summary>
    <param name="surface">The surface to upload.</param>
    <returns>Returns true if the texture was successfully uploaded and false otherwise.</returns>
    <remarks>This method wraps the <see cref="GL.glTexImage2D"/> method. See the official OpenGL documentation for
    more information.
    </remarks>
   </TexImage2D>
   <WillTextureFit>
    <summary>Determines whether a texture of the given size and format can be created.</summary>
    <param name="internalFormat">The internal format OpenGL should use.</param>
    <param name="width">The width of the texture.</param>
    <param name="height">The height of the texture.</param>
    <returns>True if the texture can be created and false otherwise.</returns>
    <remarks>This method wraps <see cref="GL.glTexImage2D"/> using <c>GL_PROXY_TEXTURE_2D</c> to
    attempt to create the texture. It's especially useful for checking whether there's enough memory to
    create a given texture. However, it cannot be guaranteed that the texture would actually fit in high
    performance video memory (that it would actually be resident on the video card). To determine that, you need
    to upload the texture and then check the <c>GL_TEXTURE_RESIDENT</c> texture parameter.
    See the official OpenGL documentation for more information.
    </remarks>
   </WillTextureFit>
  </OpenGL>

  <Primitives>
    <Pixel>
      <Common>
        <summary>Writes a pixel on the destination surface, with optional alpha blending.</summary>
        <param name="dest">The surface to draw into.</param>
      </Common>
      <XY>
        <param name="x">The X coordinate of the pixel to change.</param>
        <param name="y">The Y coordinate of the pixel to change.</param>
      </XY>
      <Pt>
        <param name="pt">The coordinate of the pixel to change.</param>
      </Pt>
      <C>
        <param name="color">The color to use. If the color contains a non-opaque alpha level, the color will be
        alpha blended over the existing pixel.
        </param>
      </C>
      <CA>
        <param name="color">The color to use. The alpha component of this color is ignored.</param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the color
        will be alpha blended over the existing pixel.
        </param>
      </CA>
    </Pixel>

    <Line>
      <HLine>
        <summary>Draws a horizontal line, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the line will be drawn.</param>
        <param name="x1">The starting X coordinate of the line.</param>
        <param name="x2">The ending X coordinate of the line.</param>
        <param name="y">The row at which the line will be drawn.</param>
      </HLine>
      <VLine>
        <summary>Draws a vertical line, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the line will be drawn.</param>
        <param name="x">The column at which the line will be drawn.</param>
        <param name="y1">The starting Y coordinate of the line.</param>
        <param name="y2">The ending Y coordinate of the line.</param>
      </VLine>
      <Line>
        <summary>Draws a line, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the line will be drawn.</param>
      </Line>
      <AA>
        <summary>Draws an antialiased line, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the line will be drawn.</param>
      </AA>
      <Pt>
        <param name="p1">The starting point of the line.</param>
        <param name="p2">The ending point of the line.</param>
      </Pt>
      <XY>
        <param name="x1">The X coordinate of the starting point of the line.</param>
        <param name="y1">The Y coordinate of the starting point of the line.</param>
        <param name="x2">The X coordinate of the ending point of the line.</param>
        <param name="y2">The Y coordinate of the ending point of the line.</param>
      </XY>
      <C>
        <param name="color">The color to use. If the color contains a non-opaque alpha level, the line will be
        alpha blended onto the surface.
        </param>
      </C>
      <CA>
        <param name="color">The color to use. The alpha component of this color is ignored.</param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the line
        will be alpha blended onto the surface.
        </param>
      </CA>
    </Line>

    <Rectangle>
      <Hollow>
        <summary>Draws a hollow rectangle, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the rectangle will be drawn.</param>
      </Hollow>
      <Filled>
        <summary>Draws a filled rectangle, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the rectangle will be drawn.</param>
      </Filled>
      <Rect>
        <param name="rect">A <see cref="Rectangle"/> describing the rectangle to draw.</param>
      </Rect>
      <Pt>
        <param name="p1">A corner of the rectangle to draw.</param>
        <param name="p2">The opposite corner of the rectangle to draw.</param>
      </Pt>
      <XY>
        <param name="x1">The X coordinate of a corner of the rectangle to draw.</param>
        <param name="y1">The Y coordinate of a corner of the rectangle to draw.</param>
        <param name="x2">The X coordinate of the opposite corner of the rectangle to draw.</param>
        <param name="y2">The Y coordinate of the opposite corner of the rectangle to draw.</param>
      </XY>
      <C>
        <param name="color">The color to use. If the color contains a non-opaque alpha level, the rectangle will be
        alpha blended onto the surface.
        </param>
      </C>
      <CA>
        <param name="color">The color to use. The alpha component of this color is ignored.</param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the rectangle
        will be alpha blended onto the surface.
        </param>
      </CA>
    </Rectangle>

    <Circle>
      <Hollow>
        <summary>Draws a hollow circle, with optional alpha blending.</summary>
        <param name="radius">The radius of the circle, in pixels.</param>
        <param name="dest">The surface onto which the circle will be drawn.</param>
      </Hollow>
      <Filled>
        <summary>Draws a filled circle, with optional alpha blending.</summary>
        <param name="radius">The radius of the circle, in pixels.</param>
        <param name="dest">The surface onto which the circle will be drawn.</param>
      </Filled>
      <AA>
        <summary>Draws an antialiased hollow circle, with optional alpha blending.</summary>
        <param name="radius">The radius of the circle, in pixels.</param>
        <param name="dest">The surface onto which the circle will be drawn.</param>
      </AA>
      <Pt>
        <param name="pt">The circle's center point.</param>
      </Pt>
      <XY>
        <param name="x">The X coordinate of the circle's center point.</param>
        <param name="y">The Y coordinate of the circle's center point.</param>
      </XY>
      <C>
        <param name="color">The color to use. If the color contains a non-opaque alpha level, the circle will be
        alpha blended onto the surface.
        </param>
      </C>
      <CA>
        <param name="color">The color to use. The alpha component of this color is ignored.</param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the circle
        will be alpha blended onto the surface.
        </param>
      </CA>
      <AAC>
        <param name="color">The base color of the circle. Surrounding pixels will be blended with this color to provide
        antialiasing. If the color contains a non-opaque alpha level, the circle will be alpha blended onto the surface.
        </param>
      </AAC>
      <AACA>
        <param name="color">The base color of the circle. Surrounding pixels will be blended with this color to provide
        antialiasing. The alpha component of this color is ignored.
        </param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the circle
        will be alpha blended onto the surface.
        </param>
      </AACA>
    </Circle>

    <Ellipse>
      <Common>
        <param name="dest">The surface onto which the ellipse will be drawn.</param>
        <param name="xRadius">The radius of the ellipse along the X axis, in pixels.</param>
        <param name="yRadius">The radius of the ellipse along the Y axis, in pixels.</param>
      </Common>
      <Hollow>
        <summary>Draws a hollow ellipse, with optional alpha blending.</summary>
        <!--<include file="documentation.xml" path="//Video/Primitives/Ellipse/Common/*"/>-->
      </Hollow>
      <Filled>
        <!--<include file="documentation.xml" path="//Video/Primitives/Ellipse/Common/*"/>-->
      </Filled>
      <AA>
        <!--<include file="documentation.xml" path="//Video/Primitives/Ellipse/Common/*"/>-->
      </AA>
      <Pt>
        <param name="pt">The ellipse's center point.</param>
      </Pt>
      <XY>
        <param name="x">The X coordinate of the ellipse's center point.</param>
        <param name="y">The Y coordinate of the ellipse's center point.</param>
      </XY>
      <C>
        <param name="color">The color to use. If the color contains a non-opaque alpha level, the ellipse will be
        alpha blended onto the surface.
        </param>
      </C>
      <CA>
        <param name="color">The color to use. The alpha component of this color is ignored.</param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the ellipse
        will be alpha blended onto the surface.
        </param>
      </CA>
      <AAC>
        <param name="color">The base color of the ellipse. Surrounding pixels will be blended with this color to provide
        antialiasing. If the color contains a non-opaque alpha level, the ellipse will be alpha blended onto the surface.
        </param>
      </AAC>
      <AACA>
        <param name="color">The base color of the ellipse. Surrounding pixels will be blended with this color to provide
        antialiasing. The alpha component of this color is ignored.
        </param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the ellipse
        will be alpha blended onto the surface.
        </param>
      </AACA>
    </Ellipse>

    <Pie>
      <Filled>
        <summary>Draws a filled pie, with optional alpha blending.</summary>
        <!--<include file="documentation.xml" path="//Video/Primitives/Pie/Common/*"/>-->
      </Filled>
      <Hollow>
        <summary>Draws a hollow pie, with optional alpha blending.</summary>
        <!--<include file="documentation.xml" path="//Video/Primitives/Pie/Common/*"/>-->
        </Hollow>
      <Pt>
        <param name="pt">The pie's center point.</param>
      </Pt>
      <XY>
        <param name="x">The X coordinate of the pie's center point.</param>
        <param name="y">The Y coordinate of the pie's center point.</param>
      </XY>
      <C>
        <param name="color">The color to use. If the color contains a non-opaque alpha level, the pie will be
        alpha blended onto the surface.
        </param>
      </C>
      <CA>
        <param name="color">The color to use. The alpha component of this color is ignored.</param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the pie
        will be alpha blended onto the surface.
        </param>
      </CA>
      <Common>
        <param name="dest">The surface into which the pie will be drawn.</param>
        <param name="radius">The radius of the pie, in pixels.</param>
        <param name="startDegs">The starting angle of the pie's arc, in degrees. 0 is to the right.</param>
        <param name="endDegs">The ending angle of the pie's arc, in degrees. 0 is to the right.</param>
      </Common>
    </Pie>
    
    <Triangle>
      <Hollow>
        <summary>Draws a hollow triangle, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the triangle will be drawn.</param>
      </Hollow>
      <Filled>
        <summary>Draws a filled triangle, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the triangle will be drawn.</param>
      </Filled>
      <AA>
        <summary>Draws an antialiased hollow triangle, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the triangle will be drawn.</param>
      </AA>
      <Pt>
        <param name="p1">The first point of the triangle.</param>
        <param name="p2">The second point of the triangle.</param>
        <param name="p3">The third point of the triangle.</param>
      </Pt>
      <XY>
        <param name="x1">The X coordinate of the first point of the triangle.</param>
        <param name="y1">The Y coordinate of the first point of the triangle.</param>
        <param name="x2">The X coordinate of the second point of the triangle.</param>
        <param name="y2">The Y coordinate of the second point of the triangle.</param>
        <param name="x3">The X coordinate of the third point of the triangle.</param>
        <param name="y3">The Y coordinate of the third point of the triangle.</param>
      </XY>
      <C>
        <param name="color">The color to use. If the color contains a non-opaque alpha level, the triangle will be
        alpha blended onto the surface.
        </param>
      </C>
      <CA>
        <param name="color">The color to use. The alpha component of this color is ignored.</param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the triangle
        will be alpha blended onto the surface.
        </param>
      </CA>
      <AAC>
        <param name="color">The base color of the triangle. Surrounding pixels will be blended with this color to
        provide antialiasing. If the color contains a non-opaque alpha level, the triangle will be alpha blended onto
        the surface.
        </param>
      </AAC>
      <AACA>
        <param name="color">The base color of the triangle. Surrounding pixels will be blended with this color to
        provide antialiasing. The alpha component of this color is ignored.
        </param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the triangle
        will be alpha blended onto the surface.
        </param>
      </AACA>
    </Triangle>
    
    <Polygon>
      <Hollow>
        <summary>Draws a hollow polygon, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the polygon will be drawn.</param>
      </Hollow>
      <Filled>
        <summary>Draws a filled polygon, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the polygon will be drawn.</param>
      </Filled>
      <AA>
        <summary>Draws an antialiased hollow polygon, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the polygon will be drawn.</param>
      </AA>
      <A>
        <param name="points">An array of points defining the polygon.</param>
      </A>
      <AL>
        <param name="points">An array of points defining the polygon.</param>
        <param name="index">The starting index into <paramref name="points"/>.</param>
        <param name="length">The number of points to read from <paramref nam="points"/>, starting from
        <paramref name="index"/>.
        </param>
      </AL>
      <C>
        <param name="color">The color to use. If the color contains a non-opaque alpha level, the polygon will be
        alpha blended onto the surface.
        </param>
      </C>
      <CA>
        <param name="color">The color to use. The alpha component of this color is ignored.</param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the polygon
        will be alpha blended onto the surface.
        </param>
      </CA>
      <AAC>
        <param name="color">The base color of the polygon. Surrounding pixels will be blended with this color to
        provide antialiasing. If the color contains a non-opaque alpha level, the polygon will be alpha blended onto
        the surface.
        </param>
      </AAC>
      <AACA>
        <param name="color">The base color of the polygon. Surrounding pixels will be blended with this color to
        provide antialiasing. The alpha component of this color is ignored.
        </param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the polygon
        will be alpha blended onto the surface.
        </param>
      </AACA>
    </Polygon>
    
    <Curve>
      <Common>
        <summary>Draws a bezier curve, with optional alpha blending.</summary>
        <param name="dest">The surface onto which the curve will be drawn.</param>
        <param name="steps">The number of interpolation steps. Higher numbers of steps will yield smoother curves,
        but with correspondingly reduced performance.
        </param>
      </Common>
      <C>
        <param name="color">The color to use. If the color contains a non-opaque alpha level, the curve will be
        alpha blended onto the surface.
        </param>
      </C>
      <CA>
        <param name="color">The color to use. The alpha component of this color is ignored.</param>
        <param name="alpha">The alpha value to use, from 0 (transparent) to 255 (opaque). If not opaque, the curve
        will be alpha blended onto the surface.
        </param>
      </CA>
      <A>
        <param name="points">An array of points defining the curve.</param>
      </A>
      <AL>
        <param name="points">An array of points defining the curve.</param>
        <param name="index">The starting index into <paramref name="points"/>.</param>
        <param name="length">The number of points to read from <paramref nam="points"/>, starting from
          <paramref name="index"/>.
        </param>
      </AL>
    </Curve>
  </Primitives>

  <PSDCodec>
   <IsPSD>
    <summary>Determines whether a file is a PSD image file that can be read by this codec.</summary>
    <returns>Returns true if the file looks like it contains PSD image data and false otherwise.</returns>
    <remarks>This function does not read all the data from the PSD image file to determine whether it could be
    loaded successfully and doesn't use any unsupported features. It only checks to see whether the image file has
    the right header signature and version number for the PSD format the codec can understand.
    </remarks>
   </IsPSD>
   <LayerReading>
    <exception cref="InvalidOperationException">
    Thrown if
    <para>The codec is not in a reading mode.</para>
    -or-
    <para>All layers have been read already.</para>
    </exception>
   </LayerReading>
   <Read>
    <summary>Reads a PSD image from the given file.</summary>
    <returns>A <see cref="PSDImage"/> containing the flattened image and all the layers.</returns>
    <!--<include file="documentation.xml" path="//Video/PSDCodec/Reading_X/*"/>-->
   </Read>
   <ReadComposite>
    <summary>Reads the flattened image from a PSD file.</summary>
    <returns>A <see cref="Surface"/> containing the flattened image from the PSD file.</returns>
    <!--<include file="documentation.xml" path="//Video/PSDCodec/Reading_X/*"/>-->
   </ReadComposite>
   <Reading_X>
    <exception cref="ArgumentException">Thrown if the file does not contain a valid PSD image.</exception>
    <exception cref="NotSupportedException">Thrown if the PSD image uses unsupported features.</exception>
    <exception cref="InvalidOperationException">Thrown if the codec is currently in a reading or writing mode.</exception>
   </Reading_X>
   <StartReading>
    <summary>Starts reading a PSD image.</summary>
    <returns>The <see cref="PSDImage"/> object in which data for this file will be stored. All fields except
    <see cref="Surface"/> fields will be populated.
    </returns>
    <!--<include file="documentation.xml" path="//Video/PSDCodec/Reading_X/*"/>-->
   </StartReading>
   <StartWriting>
    <summary>Starts writing a PSD image.</summary>
    <param name="image">A <see cref="PSDImage"/> object with all fields populated, including layer information,
    except <see cref="Surface"/> fields, which are not required.
    </param>
    <remarks>All data in <paramref name="image"/> is written into the PSD header and is expected to remain the
    same throughout the writing process.
    </remarks>
    <!--<include file="documentation.xml" path="//Video/PSDCodec/Writing_X/*"/>-->
   </StartWriting>
   <Write>
    <summary>Writes a PSD image.</summary>
    <param name="image">A <see cref="PSDImage"/> object with all fields populated, including layer information
    and image data (<see cref="Surface"/> fields).
    </param>
    <!--<include file="documentation.xml" path="//Video/PSDCodec/Writing_X/*"/>-->
   </Write>
   <Write_Surface>
    <summary>Writes a PSD image.</summary>
    <param name="surface">A <see cref="Surface"/> which will be used as the flattened image in the PSD file.</param>
    <remarks>The resulting PSD image will have no layers.</remarks>
    <exception cref="ArgumentNullException">Thrown if <paramref name="surface"/> or <paramref name="stream"/> is
    null.
    </exception>
    <exception cref="InvalidOperationException">Thrown if the codec is currently in a reading or writing mode.</exception>
   </Write_Surface>
   <Writing_X>
    <exception cref="ArgumentNullException">Thrown if <paramref name="image"/> or <paramref name="stream"/> is
    null.
    </exception>
    <exception cref="ArgumentException">Thrown if <paramref name="image"/> contains invalid data.</exception>
    <exception cref="InvalidOperationException">Thrown if the codec is currently in a reading or writing mode.</exception>
   </Writing_X>
  </PSDCodec>
  
  <Surface>
    <Cons>
      <FromBmp>
        <summary>This constructor attempts to initialize the surface from a <see cref="System.Drawing.Bitmap"/>.</summary>
        <param name="bitmap">The <see cref="System.Drawing.Bitmap"/> containing the image to initialize this
        surface with.
        </param>
      </FromBmp>
      <FromDims>
        <summary>Creates an empty surface with the given dimensions and bit depth.</summary>
        <param name="width">The width of the surface to create.</param>
        <param name="height">The height of the surface to create.</param>
        <param name="depth">The bit depth of the surface to create, in bits per pixel.</param>
      </FromDims>
      <FromFormat>
        <summary>Creates an empty surface with the given dimensions and pixel format</summary>
        <param name="width">The width of the surface to create.</param>
        <param name="height">The height of the surface to create.</param>
        <param name="format">The <see cref="PixelFormat"/> of the surface to create.</param>
      </FromFormat>
    </Cons>
    
    <Fill>
      <Whole>
        <summary>Fills the surface with the specified color.</summary>
      </Whole>
      <Rect>
        <summary>Fills a portion of the surface with the specified color.</summary>
        <param name="rect">The portion of the surface to fill.</param>
      </Rect>
      <C>
        <param name="color">The color to fill with.</param>
        <remarks>The color will be converted to a raw pixel value with <see cref="MapColor(Color)"/> before the area
        is filled. This method should not be called while the surface is locked. This method respects the
        <see cref="ClipRect"/> set on the surface.
        </remarks>
      </C>
      <R>
        <param name="color">The raw pixel value to fill with.</param>
        <remarks>This method should not be called while the surface is locked. This method respects the
        <see cref="ClipRect"/> set on the surface.
        </remarks>
      </R>
    </Fill>
    
    <Blit>
      <Whole>
        <summary>Blits this surface onto a destination surface at the given point.</summary>
        <param name="dest">The destination surface to blit onto.</param>
      </Whole>
      <Part>
        <summary>Blits a portion of this surface onto a destination surface at the given point.</summary>
        <param name="dest">The destination surface to blit onto.</param>
        <param name="src">The portion of this surface to blit.</param>
      </Part>
      <Pt>
        <param name="dpt">The destination point where the blit will begin.</param>
      </Pt>
      <XY>
        <param name="dx">The X coordinate of the destination point where the blit will begin.</param>
        <param name="dy">The Y coordinate of the destination point where the blit will begin.</param>
      </XY>
      <remarks>
        Blitting respects the <see cref="ClipRect"/> set on the destination surface. This method should not be called when
        either surface is locked. The logic of alpha blending and color keys works as follows:
        <code>
IF UsingAlpha THEN
  IF has alpha channel (Format.AlphaMask != 0) THEN
    Blit using alpha channel and ignore the color key
  ELSE IF UsingKey THEN
    Blit using the color key (ColorKey) and the surface alpha (Alpha)
  ELSE
    Blit using the surface alpha (Alpha)
ELSE IF UsingKey
  Blit using the color key (ColorKey)
ELSE
  Opaque rectangular blit (if both surfaces have an alpha channel,
  the alpha information will be COPIED)
</code>
The effects of surfaces with various combinations of alpha channels is as follows:
<code>
USA = Source surface's UsingAlpha value
SHA = Source surface has an alpha channel (Format->AlphaMask!=0)
DHA = Destination surface has an alpha channel (Format->AlphaMask!=0)
UsingKey refers to the source surface's UsingKey value.
USA  SHA  DHA  Effect
 N    N    N   The pixels are copied from the source. If UsingKey is set, only the
               pixels not matching the color key value are copied.
 N    N    Y   The pixels are copied from the source and the alpha value of the
               copied pixels is set to opaque. If UsingKey is set, only the pixels
               not matching the color key value are copied.
 N    Y    N   The RGB data is copied from the source. The source alpha channel and
               the surface alpha value are ignored. If UsingKey is set, only the
               pixels not matching the color key value are copied.
 N    Y    Y   The RGBA data is copied to the destination surface. If UsingKey is
               set, only the pixels not matching the color key value are copied.
 Y    N    N   The source is alpha blended with the destination using the surface
               alpha value. If UsingKey is set, only the pixels not matching the
               color key value are copied.
 Y    N    Y   The source is alpha blended with the destination using the surface
               alpha value. If UsingKey is set, only the pixels not matching the
               color key value are copied. The alpha channel of the copied pixels
               is set to opaque.
 Y    Y    N   The source is alpha-blended with the destination, using the alpha
               channel. The color key and surface alpha are ignored.
 Y    Y    Y   The source is alpha blended with the destination using the source
               alpha channel. The alpha channel in the destination surface is
               unchanged. The color key is ignored.
        </code>
      </remarks>
    </Blit>

    <Blend>
      <remarks>
        Blending respects the <see cref="ClipRect"/> set on the destination surface. This method can be called when either
        surface is locked. The logic of alpha blending and color keys works as follows:
        <code>
IF UsingAlpha THEN
  IF has alpha channel (Format.AlphaMask != 0) THEN
    Blit using alpha channel and ignore the color key
  ELSE IF UsingKey THEN
    Blit using the color key (ColorKey) and the surface alpha (Alpha)
  ELSE
    Blit using the surface alpha (Alpha)
ELSE IF UsingKey
  Blit using the color key (ColorKey)
ELSE
  Opaque rectangular blit (if both surfaces have an alpha channel,
  the alpha information will be COPIED)
        </code>
        Each source pixel is first blended with the destination pixel using the blend mode, without considering alpha values, to
        produce a result pixel. Then, the result pixel is copied or alpha blended with the destination as follows.
        <code>
USA = Source surface's UsingAlpha value
SHA = Source surface has alpha (Alpha != 255 or Format->AlphaMask!=0)
HSA = Destination surface has an alpha channel (Format->AlphaMask!=0)
UsingKey refers to the source surface's UsingKey value, and the "source alpha" is
a combination of the source pixel's alpha channel (if any) and the source surface's
alpha value (if not opaque). For instance, if the alpha channel value is 128 and
the surface alpha value is 128, the effective source alpha will be 64.
USA  SHA  Effect
 N    *   The result pixels are copied to the destination. If UsingKey is set,
          only the source pixels not matching the color key value are
          processed. The destination alpha channel is unchanged.

 Y    N   The result pixels are copied to the destination. If UsingKey is set,
          only the source pixels not matching the color key value are
          processed. The destination alpha channel is unchanged.

 Y    Y   The result pixels are alpha-blended with the destination, using the
          source alpha. If UsingKey is set, only the source pixels not matching
          the color key value are processed.  The destination alpha channel is
          unchanged.
        </code>
      </remarks>
    </Blend>
    
    <GetPixel>
      <C>
        <summary>Returns the color of the pixel at the specified point.</summary>
        <returns>The <see cref="Color"/> of the pixel.</returns>
        <remarks>This method reads the raw pixel value and calls <see cref="MapColor(uint)"/> to convert it to a
        <see cref="Color"/>.
        This method is quite inefficient. Also, it uses <see cref="Lock"/> to lock the
        surface first if necessary. If you are reading/writing many pixels at once, you should consider locking
        the surface before all the operations and unlocking it afterwards, or doing direct pixel access yourself
        using <see cref="Data"/>.
        </remarks>
      </C>
      <R>
        <summary>Gets the raw value of the pixel at the specified point.</summary>
        <returns>The raw pixel value for the specified point.</returns>
        <remarks>This method is quite inefficient.
        Also, it uses <see cref="Lock"/> to lock the surface first if necessary. If you are reading/writing many
        pixels at once, you should consider locking the surface before all the operations and unlocking it afterwards,
        or doing direct pixel access yourself using <see cref="Data"/>.
        </remarks>
      </R>
      <Pt>
        <param name="point">The point whose color value will be returned.</param>
      </Pt>
      <XY>
        <param name="x">The X coordinate of the point whose color value will be returned.</param>
        <param name="y">The Y coordinate of the point whose color value will be returned.</param>
      </XY>
    </GetPixel>
    
    <PutPixel>
      <C>
        <summary>Sets the color of the pixel at the specified point.</summary>
        <param name="color">The color value to set the pixel to.</param>
        <remarks>This method calls <see cref="MapColor(Color)"/> to convert the color into a raw pixel value.
        This method respects the <see cref="ClipRect"/> set up for the surface. This method is quite inefficient.
        Also, it uses <see cref="Lock"/> to lock the surface first if necessary. If you are reading/writing many
        pixels at once, you should consider locking the surface before all the operations and unlocking it afterwards,
        or doing direct pixel access yourself using <see cref="Data"/>.
        </remarks>
      </C>
      <R>
        <summary>Sets the raw pixel value of the pixel at the specified point.</summary>
        <param name="color">The raw color value to set the pixel to.</param>
        <remarks>This method respects the <see cref="ClipRect"/> set up for the surface.
        This method is quite inefficient.
        Also, it uses <see cref="Lock"/> to lock the surface first if necessary. If you are reading/writing many
        pixels at once, you should consider locking the surface before all the operations and unlocking it afterwards,
        or doing direct pixel access yourself using <see cref="Data"/>.
        </remarks>
      </R>
      <Pt>
        <param name="point">The point whose color value will be set.</param>
      </Pt>
      <XY>
        <param name="x">The X coordinate of the point whose color value will be set.</param>
        <param name="y">The Y coordinate of the point whose color value will be set.</param>
      </XY>
    </PutPixel>
    
    <SetPalette>
      <Common>
        <exception cref="ArgumentNullException">Thrown if <paramref name="colors"/> is null.</exception>
        <param name="colors">An array of <see cref="Color"/> to set the palette with.</param>
      </Common>
      <ANCommon>
        <param name="numColors">The number of colors to set.</param>
        <remarks>If <paramref name="numColors"/> is smaller than the number of colors in the palette, part of the
        palette will remain unchanged.
        </remarks>
      </ANCommon>

      <Logical>
        <summary>Sets the logical palette colors.</summary>
        <!--<include file="documentation.xml" path="//Video/Surface/SetPalette/Common/*"/>-->
      </Logical>

      <A>
        <remarks>If <paramref name="colors"/> contains too few colors, part of the palette will remain unchanged.
        </remarks>
      </A>
      <AN>
        <!--<include file="documentation.xml" path="//Video/Surface/SetPalette/ANCommon/*"/>-->
        <remarks>If <paramref name="numColors"/> is smaller than the number of colors in the palette, part of the
        palette will remain unchanged.
        </remarks>
        <exception cref="ArgumentOutOfRangeException">Thrown if the number of colors would overflow the palette.
        </exception>
      </AN>
      <AA>
        <!--<include file="documentation.xml" path="//Video/Surface/SetPalette/AN/*"/>-->
        <param name="startIndex">The starting index within the palette where colors will be written.</param>
        <param name="startColor">The starting index within the color array from where colors will be read.</param>
        <exception cref="ArgumentOutOfRangeException">Thrown if the number of colors would overflow the palette or
        one of the indices are invalid.
        </exception>
      </AA>
      <EN>
        <exception cref="ArgumentOutOfRangeException">Thrown if the number of colors would overflow the palette.
        </exception>
      </EN>
    </SetPalette>
    
    <CreateCompatible>
      <summary>Creates a surface with the same pixel format as this one, and a specified size.</summary>
      <param name="width">The width of the new surface.</param>
      <param name="height">The height of the new surface.</param>
      <returns>A <see cref="Surface"/> with the same pixel format as this one.</returns>
    </CreateCompatible>
    
    <CloneDisplay>
      <summary>Returns a copy of this surface in the same general format as the display surface, suitable for fast
      blitting.
      </summary>
      <returns>A new <see cref="Surface"/> containing the same image data, converted to the same general pixel format
      of the display surface. The new surface will have an alpha channel if this surface has an alpha channel.
      </returns>
    </CloneDisplay>
  </Surface>
 </Video>
</GameLib>