path: root/o3d/plugin/idl/texture.idl

/*
 * Copyright 2009, Google Inc.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *
 *     * Redistributions of source code must retain the above copyright
 * notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above
 * copyright notice, this list of conditions and the following disclaimer
 * in the documentation and/or other materials provided with the
 * distribution.
 *     * Neither the name of Google Inc. nor the names of its
 * contributors may be used to endorse or promote products derived from
 * this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

namespace o3d {

%[
  The Texture class is a base class for image data used in texture mapping.
%]
[include="core/cross/texture_base.h"] class Texture : ParamObject {
  %[
    \var Format,
    \li UNKNOWN_FORMAT
    \li XRGB8
    \li ARGB8
    \li ABGR16F
    \li R32F
    \li ABGR32F
    \li DXT1
    \li DXT3
    \li DXT5

    The in-memory format of the texture bitmap.

    NOTE: The R32F format is different on GL vs D3D. If you use it in a shader
    you must only use the red channel. The green, blue and alpha channels are
    undefined.

    For example:
    \code
    ...

    // The texture sampler is used to access the texture bitmap in the fragment
    // shader.
    sampler texSampler0;

    ...

    // input parameters for our vertex shader
    struct PixelShaderInput {
      float4 position : POSITION;
      float2 texcoord : TEXCOORD0;  // Texture coordinates
    };

    float4 pixelShaderFunction(PixelShaderInput input): COLOR {
      // ** Use only valid channels. ** ---------+
      //                                         |
      //                                         V
      return tex2D(texSampler0, input.texcoord).rrrr;
    }
    \endcode
  %]
  enum Format {
    UNKNOWN_FORMAT,
    XRGB8,
    ARGB8,
    ABGR16F,
    R32F,
    ABGR32F,
    DXT1,
    DXT3,
    DXT5
  };

  %[
    The memory format used for storing the bitmap associated with the texture
    object.
  %]
  [getter] Format format;

  %[
    The number of mipmap levels used by the texture.
  %]
  [getter] int levels;

  %[
    True of all the alpha values in the texture are 1.0
  %]
  [getter, getter, setter] bool alpha_is_one;
};  // Texture

%[
  A class for 2D textures that defines the interface for getting
  the dimensions of the texture, its memory format and number of mipmap levels.
%]
[include="core/cross/texture.h"] class Texture2D : Texture {
  %[
    The width of the texture, in texels.
  %]
  [getter] int width;

  %[
    The height of the texture, in texels.
  %]
  [getter] int height;

  %[
    Returns a RenderSurface object associated with a mip_level of a texture.

    \param mip_level: The mip-level of the surface to be returned.
    \param pack: The pack in which the surface will reside.
    \return The RenderSurface object.
  %]
  RenderSurface? GetRenderSurface(int mip_level, Pack pack);

  // TODO: Add Get, GetRect, SetRect and/or expose Bitmap.
  %[
    Sets the values of the data stored in the texture.

    It is not recommend that you call this for large textures but it is useful
    for making simple ramps or noise textures for shaders.

    NOTE: the number of values must equal the size of the texture * the number
     of elements. In other words, for a XRGB8 texture there must be
     width * height * 3 values. For an ARGB8, ABGR16F or ABGR32F texture there
     must be width * height * 4 values. For an R32F texture there must be
     width * height values.

    NOTE: the order of channels is R G B for XRGB8 textures and R G B A
    for ARGB8, ABGR16F and ABGR32F textures so for example for XRGB8 textures\n
    \n
    [1, 0, 0] = a red pixel\n
    [0, 0, 1] = a blue pixel\n
    \n
    For ARGB8, ABGR16F, ABGR32F textures\n
    \n
    [1, 0, 0, 0] = a red pixel with zero alpha\n
    [1, 0, 0, 1] = a red pixel with one alpha\n
    [0, 0, 1, 1] = a blue pixel with one alpha\n

    \param level the mip level to update.
    \param values Values to be stored in the buffer.
  %]
  [nocpp, userglue, include="core/cross/math_utilities.h"]
  void Set(int level, float[] values);

  [verbatim=cpp_glue] %{
    void userglue_method_Set(o3d::Texture2D* self,
                             int level,
                             const std::vector<float>& values) {
      if (level < 0 || level >= self->levels()) {
        O3D_ERROR(self->service_locator())
            << "level (" << level << " out of range";
        return;
      }
      unsigned width = std::max(self->width() >> level, 1);
      unsigned height = std::max(self->height() >> level, 1);
      unsigned num_elements;
      unsigned swizzle[4] = {2, 1, 0, 3};
      switch (self->format()) {
        case o3d::Texture::XRGB8:
          num_elements = 3;
          break;
        case o3d::Texture::R32F:
          swizzle[0] = 0;
          num_elements = 1;
          break;
        case o3d::Texture::ARGB8:
        case o3d::Texture::ABGR16F:
          num_elements = 4;
          break;
        case o3d::Texture::ABGR32F: {
          num_elements = 4;
          const o3d::Texture::RGBASwizzleIndices& indices =
             self->GetABGR32FSwizzleIndices();
          for (int ii = 0; ii < 4; ++ii) {
            swizzle[ii] = indices[ii];
          }
          break;
        }
        default:
          O3D_ERROR(self->service_locator())
            << "Texture::Set not supported for this type of texture";
          return;
      }
      unsigned needed = num_elements * width * height;
      if (values.size() != needed) {
        O3D_ERROR(self->service_locator())
          << "needed " << needed << " values but " << values.size()
          << " passed in.";
        return;
      }
      void* data;
      if (!self->Lock(level, &data)) {
        O3D_ERROR(self->service_locator()) << "could not lock texture";
        return;
      }
      switch (self->format()) {
        case o3d::Texture::ABGR16F: {
          unsigned short* destination = static_cast<unsigned short*>(data);
          unsigned short* end = destination + width * height * num_elements;
          const float* source = &values[0];
          while (destination < end) {
            for (int element = 0; element < num_elements; ++element) {
              destination[element] = Vectormath::Aos::FloatToHalf(
                  source[swizzle[element]]);
            }
            destination += num_elements;
            source += num_elements;
          }
          break;
        }
        case o3d::Texture::R32F:
        case o3d::Texture::ABGR32F: {
          float* destination = static_cast<float*>(data);
          float* end = destination + width * height * num_elements;
          const float* source = &values[0];
          while (destination < end) {
            for (int element = 0; element < num_elements; ++element) {
              destination[element] = source[swizzle[element]];
            }
            destination += num_elements;
            source += num_elements;
          }
          break;
        }
        default: {
          unsigned char* destination = static_cast<unsigned char*>(data);
          unsigned char* end = destination + width * height * 4;
          const float* source = &values[0];
          while (destination < end) {
            destination[0] = static_cast<unsigned char>(
                source[swizzle[0]] * 255.0f);
            destination[1] = static_cast<unsigned char>(
                source[swizzle[1]] * 255.0f);
            destination[2] = static_cast<unsigned char>(
                source[swizzle[2]] * 255.0f);
            destination[3] = (num_elements == 4) ?
                static_cast<unsigned char>(source[swizzle[3]] * 255.0f) : 255;
            destination += 4;
            source += num_elements;
          }
          break;
        }
      }
      if (!self->Unlock(level)) {
        O3D_ERROR(self->service_locator()) << "could not unlock texture";
      }
    }
  %}
};  // Texture2D


%[
TextureCUBE is a class for textures used for cube mapping.  A cube texture
stores bitmaps for the 6 faces of a cube and is addressed via three texture
coordinates.
%]
[include="core/cross/texture.h"] class TextureCUBE : Texture {
  %[
    \var CubeFace,
    \li FACE_POSITIVE_X
    \li FACE_NEGATIVE_X
    \li FACE_POSITIVE_Y
    \li FACE_NEGATIVE_Y
    \li FACE_POSITIVE_Z
    \li FACE_NEGATIVE_Z

    The names of each of the six faces of a cube map texture.
  %]
  enum CubeFace { FACE_POSITIVE_X,
                  FACE_NEGATIVE_X,
                  FACE_POSITIVE_Y,
                  FACE_NEGATIVE_Y,
                  FACE_POSITIVE_Z,
                  FACE_NEGATIVE_Z };

  %[
    The length of each edge of the cube, in texels.
  %]
  [field_access=private, getter] int edge_length;

  %[
    Returns a RenderSurface object associated with a given cube face and
    mip_level of a texture.

    \param face The cube face from which to extract the surface.
    \param mip_level The mip-level of the surface to be returned.
    \param pack: The pack in which the surface will reside.
    \return The RenderSurface object.
  %]
  RenderSurface? GetRenderSurface(CubeFace face, int mip_level, Pack pack);
};  // TextureCUBE

}  // namespace o3d