Product Home • Class Index • Download

CK_Viewport

CK_Object
   |
   +----CK_Component
           |
           +----CK_Primitive
                   |
                   +----CK_Viewport

The CK_Viewport is a primitive component that allocates a rectangle on the screen where the application is responsible for rendering a scene, or anything else it desires. The viewport is typically where a game application's world-view is located, such as a 3-D 'Doom' type world, or a 2-D tiled map such as those found in many real-time strategy games.

The Chilkat engine renders the viewport by first setting up the DirectDraw clipping, and then calling the user's CK_Render callback object. One of the properties of the viewport is to specify a CK_Render object that the application provides to render the contents of the viewport. The CK_DirectDraw class provides direct access to the DirectDraw objects and surfaces used by the library. This allows the application to use DirectDraw functions to render the viewport, if desired.

The application can control when the viewport can be re-rendered in two ways. The first way is to call the CK_Component::setDirty() function to notify the Chilkat engine that the viewport is dirty and needs to be redrawn. Calling setDirty() simply causes the Chilkat engine to mark the component as dirty and redraw it in the next iteration of the mainLoop().

The second way to have the viewport re-rendered is to tell the viewport to observe a CK_Subject. Whenever the subject is updated the viewport will be re-rendered. The viewport will also be re-rendered if the subject is deleted.

Properties

• CP_CallbackArg1 - An integer value to be passed to the screen's componentCB method when an event occurs in this component.
• CP_CallbackArg2 - Same as CP_CallbackArg1.
• CP_Cursor - The cursor to be displayed when the mouse pointer is over the component. (v1.02)
• CP_Height - The height in pixels of the viewport.
• CP_RelativeX - Only used when this component is a child of a CK_BBoard or CK_ClipWindow. It is the X position of the component relative to the parent's left edge.
• CP_RelativeY - Only used when this component is a child of a CK_BBoard or CK_ClipWindow. It is the Y position of the component relative to the parent's top edge.
• CP_Render - A pointer to a CK_Render object provided by the application that renders the contents of the viewport.
• CP_Width - The width in pixels of the viewport.
• CP_X - The absolute X-position, in screen coordinates, of the component. This can only be set for the top-level component of a screen or a dialog.
• CP_Y - The absolute Y-position, in screen coordinates, of the component. This can only be set for the top-level component of a screen or a dialog.
• CP_ZOrder - Used when this component is a child of a CK_BBoard. The CK_BBoard uses this value to determine the order in which children are drawn. Smaller Z-order values are drawn before larger Z-order values.

Public Methods:

The CK_Viewport provides a few additional methods that can be used, if desired, to help render the viewport contents.

• void drawBitmap(int viewPort_x, int viewPort_y, int bitmap_x, int bitmap_y, int width, int height, const CK_Bitmap *bitmap, int paletteIdx);

Draws a bitmap, or a portion of a bitmap in the viewport.

Parameters

viewPort_x

The destination x-coordinate relative to the left edge of the viewport.

viewPort_y

The destination y-coordinate relative to the top of the viewport.

bitmap_x

The source x-coordinate within the bitmap.

bitmap_y

The source y-coordinate within the bitmap.

width

The width of the portion of the bitmap to be drawn. Passing a 0 will cause the entire width of the bitmap to be drawn.

height

The height of the portion of the bitmap to be drawn. Passing a 0 will cause the entire height of the bitmap to be drawn.

bitmap

The bitmap to be drawn.

paletteIdx

If the bitmap is 8 bits per pixel, this is the index of the palette in the bitmap's palette set to be used.

• void fillWithColor(RGBQUAD &rgb);

Fills the entire viewport with a solid color.

Parameters

rgb

The fill color.

• void getViewportRect(RECT &rect) const;

Gets the screen coordinates of the top, left, bottom, and right edges of the viewport.

Parameters

rect

Filled with the coordinates of the viewport's rectangle. The top,left of the rectangle cooresponds to the pixel at the top-left corner of the viewport. The bottom,right of the rectangle corresponds to the bottom-right pixel of the viewport.

• void ignoreSubject(CK_Subject *subject);

Causes the viewport to stop observing a subject.

Parameters

subject

The subject to stop observing.

• void observeSubject(CK_Subject *subject);

Causes the viewport to start observing a subject. Each time the subject is updated, the viewport will be redrawn. The viewport will also be redrawn if the subject is deleted.

Parameters

subject

The subject to stop observing.

Example of creating a viewport:

extern CK_BBoard *bb;
extern CK_Render *render;

// Places a 400x300 viewport on a bulletin board at location 10,10 from the
// top-left corner of the bulletin board.
CK_Viewport *viewport = (CK_Viewport *) CreateComponent(CT_Viewport, bb,
    CP_RelativeX, 10,
    CP_RelativeY, 10,
    CP_Width, 400,
    CP_Height, 300,
    CP_Render, render,
    0);