/*

* Copyright (c) 2006-2007 Nokia Corporation and/or its subsidiary(-ies). 

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:   Declares MHuiSegmentedTexture interface class for texture image objects.

*

*/

#ifndef __HUISEGMENTEDTEXTURE_H__

#define __HUISEGMENTEDTEXTURE_H__

#include <e32base.h>

/* Forward declarations. */

class THuiTextureHandle;

/**

 * MHuiSegmentedTexture is an abstract base class for texture image objects.

 * It specifies one or more texture images that comprise a larger (virtual) image.

 * THuiImage refers to objects that implement MHuiSegmentedTexture.

 *

 * A segmented texture is a texture that is composed of one or more segments.

 * Each segment has a position, dimensions, and a name that identifies the texture

 * image of the segment. The purpose is that it is possible to compose large images

 * out of smaller segments. The segments can overlap.

 *

 * One use case is where the OpenGL texture size is limited (e.g., 256x256). A class

 * implementing MHuiSegmentedTexture would in this case split the uploaded source

 * image to multiple segments and create a different OpenGL texture for each. All

 * of the segments would still be hidden inside the implementing

 * MHuiSegmentedTexture-derived class, though, so it could be treated as a single entity.

 *

 * When an object implements the MHuiSegmentedTexture interface, it can be drawn using

 * the DrawImage() methods in CHuiGc (since THuiImage specifies the image as

 * MHuiSegmentedTexture).

 *

 * @note CHuiGc and CHuiTexture only support single-segment textures at the moment.

 * @see CHuiGles10Texture

 * @see CHuiTexture

 * @see CHuiGc

 * @see THuiImage

 *

 */

class MHuiSegmentedTexture

    {

public:

    /** @beginAPI */

    /** Construction / Destruction */

    /**

     * Virtual destructor, needed because we have a couple of implemented

     * methods.

     */

    IMPORT_C virtual ~MHuiSegmentedTexture();

    /* Methods. */

    /**

     * Returns the logical size of this texture. Ie. the original size of the

     * image represented with this texture. This size is independent of the

     * possible segmentation of this texture.

     *

     * On the other hand the actual texture size may

     * vary across segments and typically has some driver/hw limitations.

     *

     * Note that all the segments must be contained inside the logical

     * area defined with this function.

     *

     * @see SegmentSize() To return logical size for a particular texture segment.

     * @see SegmentOffset() To return logical position for a particular texture segment.

     * @see SegmentTextureSize() To return texture size for a segment.

     */

    virtual TSize Size() const = 0;

    /**

     * Determines how many segments the texture has. Will return 1 if

     * the texture is not segmented.

     *

     * @return  Number of segments in this texture.

     */

    virtual TInt SegmentCount() const = 0;

    /**

     * Determines the texture name of a segment. For example with

     * OpenGL ES renderer, this will be the texture id generated

     * with glGenTextures().

     *

     * @param aSegment Segment index to access.

     */

    virtual TUint SegmentName(TInt aSegment) const = 0;

    /**

     * Determines the logical size of a texture segment.

     * Can be non-power-of-two (NPOT) and may be different

     * from the actual texture size.

     *

     * @param aSegment Valid segment index for this texture.

     * @see Size() to return logical size of the whole texture.

     * @see SegmentTextureSize() to determine the actual resolution of

     * the texture.

     */

    virtual TSize SegmentSize(TInt aSegment) const = 0;

    /**

     * Determines the actual resolution of the texture used

     * by the segment. Most likely only Power-of-Two, unless NPOT

     * supported by the graphics library.

     *

     * @param aSegment Valid segment index for this texture.

     */

    virtual TSize SegmentTextureSize(TInt aSegment) const = 0;

    /**

     * Determines the logical offset for a texture segment.

     *

     * @param aSegment Valid segment index for this texture.

     */

    virtual TPoint SegmentOffset(TInt aSegment) const = 0;

    /**

     * Returns a handle to given texture segment. Defaults to first segment.

     */

    IMPORT_C THuiTextureHandle Handle(TInt aSegment = 0) const;

    /**

     * Binds given texture segment to the texture target. Binding makes

     * the texture segment active.

     *

     * @param aSegment Index of a segment. Defaults to the first segment.

     * @param aTextureUnit  Which (multi-)texture unit to bind to. The default

     * value binds to the first texture unit (single-texturing mode).

     * @see SegmentCount() to get the number of available segments.

     */

    IMPORT_C void Bind(TInt aSegment = 0, TInt aTextureUnit = 0) const;

    /** @endAPI */

    };

#endif // __HUISEGMENTEDTEXTURE_H__