Chapter 22:
Advanced Drawing (OpenGL)
Functions
 

OGL_BeginFirstPass(); Open GL/Begin First Pass

 

OGL_BlitOffscreen(); Open GL/Blit Off-Screen

 

OGL_DrawBegin(); Open GL/Draw Begin

 

OGL_DrawEnd(); Open GL/Draw End

 

OGL_GetChartStatus(); Open GL/Get Chart Status

 

OGL_GetOffscreenDC(); Open GL/Get Off-Screen Device Context

 

OGL_InitOffscreen(); Open GL/Initialize Off-Screen

 

OGL_RegisterOffscreenPort(); Open GL/Register Off-Screen Port

 

OGL_RegisterPort(); Open GL/Register Port

 

OGL_SetTessellationDetail(); Open GL/Set Tessellation Detail

OGL_BeginFirstPass()

 

This function prepares the Advanced 3D Rendering engine for a series of drawing passes by resetting counter values to their initial values. This should be called before the OGL_DrawBegin() / OGL_DrawEnd() loop.

Syntax:

void PUBLIC
OGL_BeginFirstPass (
     void
);

Input:

None

Return:

None

Example:

case WM_PAINT:
// assume the local variables here
// are defined at the top
// of the WndProc function
hdc = BeginPaint(hWnd, &ps);
OGL_GetChartStatus(pGraph, &bDoAdv3D, NULL,&bIs2D3D);
OGL_BeginFirstPass();

Also See:

OGL_DrawBegin(), OGL_DrawEnd()

OGL_BlitOffscreen()

 

This function copies a portion of the off-screen buffer to the given destination port (hDestPort).

Syntax:

INT16 PUBLIC
OGL_BlitOffscreen (
     HDC hDestPort,
     Rect * rcDest
);

Input:

hDestPort: The platform-specific destination port to which the off-screen bitmap will be copied (in Windows, this is an HDC).

 

rcDest: The destination rectangle where the off-screen image will be copied. The size of this rectangle can be smaller than the maximum sizes used in OGL_InitializeOffscreen(), in which case only a portion of the buffer will be copied. The values used in this rectangle must be in the device coordinate space of the DC specified in hDestPort. If this function is called between a DrawBegin/DrawEnd pair, NULL may be used for this parameter. If NULL is used, it will cause the rectangle set by DESetDestRect() to be used as the destination of the copy. See the Rect structure in Appendix A.

Return:

INT16: TRUE/FALSE

 

TRUE=

Successful

 

FALSE=

Failure

Notes:

If the bounds of the current client window are retrieved from Windows GetClientRect(), you may need to call LPToDP() on the rectangle's points to translate them to the proper coordinate space.

Example:

if(bDoAdv3D)
{
     OGL_DrawEnd(lOGLRef, pDE, pGraph);
     if(bDoAnotherPass)
          goto do_pass;
     OGL_BlitOffscreen(hdc NULL);
}

Also See:

OGL_InitializeOffscreen

OGL_DrawBegin()

 

This function begins an advanced 3D-drawing pass by setting the destination port and graph information and setting up initial values for a single pass.

Syntax:

BOOLEAN16 PUBLIC
OGL_DrawBegin (
     INT32 lRef,
     DrawEnvPtr pDE,
     GraphPtr pGraph
);

Input:

lRef: OGL Reference of the port that should be drawn to. This should be a value received from OGL_RegisterPort() or OGL_RegisterOffscreenPort().

 

pDE: Pointer to the Draw Environment that will be used for drawing the chart. This parameter must be the same as the value passed to DrawBegin(), which must have been previously called.

 

pGraph: Pointer to the Graph that will be drawn.

Return:

BOOLEAN16: TRUE/FALSE

 

TRUE=

another pass should be made after drawing has completed and OGL_DrawEnd() is called

 

FALSE=

no more passes should be made

Example:

if(bDoAdv3D)
{
     if(bIs2D3D)
     DESetDrawProcs(pDE,
          DE_PROCS_ADVANCED_3D);
     else DESetDrawProcs(pDE,
          DE_PROCS_NORMAL);
     DrawBegin(pDE);
     bDoAnotherPass = OGL_DrawBegin(
          lOGLRef, pDE, pGraph);
}

Also See:

OGL_DrawEnd, OGL_RegisterPort, OGL_RegisterOffscreenPort, OGL_BeginFirstPass

OGL_DrawEnd()

 

This function marks the end of the current pass of advanced 3D rendering.

Syntax:

BOOLEAN16 PUBLIC
OGL_DrawEnd (
     INT32 lRef,
     DrawEnvPtr pDE,
     GraphPtr pGraph
);

Input:

lRef: OGL Reference of the port that has been drawn to. This should be the same value passed in OGL_DrawBegin().

 

pDE: A pointer to the Draw Environment that has been used for drawing the chart. This should be the same value passed in OGL_DrawBegin().

 

pGraph: A pointer to the Graph that has been drawn. This should be the same value passed in OGL_DrawBegin().

Return:

BOOLEAN16: TRUE/FALSE

 

TRUE=

cleanup was successful

 

FALSE=

unsuccessful

Example:

if(bDoAdv3D)
{
     OGL_DrawEnd(lOGLRef, pDE, pGraph);
     if(bDoAnotherPass)
          goto do_pass;
     OGL_BlitOffscreen(hdc NULL);
}

Also See:

OGL_DrawBegin

OGL_GetChartStatus()

 

This function returns information about three top-level Advanced 3D settings for the given graph: 1) whether it will draw an advanced 3D graph, 2) whether it will draw advanced 3D titles, and 3) whether it is a 2D3D graph.

Syntax:

void PUBLIC
OGL_GetChartStatus (
     GraphPtr pGraph,
     BOOLEAN16 * pbDoAdv3D,
     BOOLEAN16 * pbDoAdv3DTitles,
     BOOLEAN16 * pbIs2D3D
);

Input:

pGraph; Pointer to the graph about which you want information.

 

pbDoAdv3D; Pointer to a BOOLEAN16 that will be set to TRUE or FALSE:

 

TRUE=

graph is set for advanced 3D drawing

 

FALSE=

normal drawing

 

pbDoAdv3DTitles; Pointer to a BOOLEAN16 that will be set to TRUE or FALSE:

 

TRUE=

graph is set for advanced 3D title drawing

 

FALSE=

normal drawing

 

pbIs2D3D; Pointer to a BOOLEAN16 that will be set to TRUE or FALSE:

 

TRUE=

graph is a 2D3D (Advanced 3D version of a 2.5D)

 

FALSE=

normal drawing

Return:

None.

Example:

case WM_PAINT:
//
// assume the local variables here
// are defined at the top
// of the WndProc function
//
hdc = BeginPaint(hWnd, &ps);
OGL_GetChartStatus(pGraph, &bDoAdv3D, NULL,&bIs2D3D);
OGL_BeginFirstPass();

Notes:

You can also use A3D_ADV_DOADV_CHART and A3D_ADV_DOADV_TITLES attributes to determine if the entire chart and/or chart titles are drawn in advanced drawing mode.

Also See:

A3D_ADV_DOADV_CHART, A3D_ADV_DOADV_TITLES

OGL_GetOffscreenDC()

 

This function gets the Windows memory DC of the off-screen bitmap.

Syntax:

HDC PUBLIC OGL_GetOffscreenDC (void);

Input:

None.

Return:

HDC: The Windows HDC of the memory device context attached to the off-screen DIB used by OpenGL drawing.

Notes:

If NULL is returned, it can be assumed that off-screen drawing has not been initialized or there was a failure in initialization.

Also See:

OGL_InitializeOffscreen, OGL_BlitOffscreen

OGL_InitOffscreen()

 

This function prepares the Advanced 3D Rendering engine for drawing to an off-screen buffer. A bitmap with the given width (nMaxWidth) and height (nMaxHeight) and a 24-bit depth is created for use as a drawing surface.

Syntax:

INT16 PUBLIC OGL_InitOffscreen (
     BOOLEAN16 bRenderToDIB,
     HDC hPort,
     INT16 nMaxWidth,
     INT16 nMaxHeight
);

Input:

bRenderToDIB; TRUE/FALSE

 

TRUE=

Sets the engine into off-screen rendering mode

 

FALSE=

Takes the engine back to normal drawing mode.

 

hPort; A platform-specific port that will be used as the basis for some of the off-screen buffer's attributes.

 

nMaxWidth; The maximum width that will be needed for drawing a chart. This will be the initial width of the off-screen buffer.

 

nMaxHeight; The maximum height that will be needed for drawing a chart. This will be the initial height of the off-screen buffer.

Return:

INT16; TRUE = Success / FALSE = Initialization Failed.

Notes:

Currently this function only needs to be called once at program start time. In the future, this function will be able to be called subsequent times with different width and height values to resize the off-screen buffer.

Also See:

OGL_RegisterOffscreenPort()

OGL_RegisterOffscreenPort()

 

This function creates an OGL Reference that is linked to the off-screen buffer for drawing. This function must be called after OGL_InitializeOffscreen() has successfully returned. It returns an OGL Reference that is the internal cookie the Advanced 3D Engine uses to identify an output context. The host application must save this value because it is required to draw to the off-screen bitmap.

Syntax:

INT32 PUBLIC
OGL_RegisterOffscreenPort (
     void
);

Input:

none.

Return:

INT32; The OGL Reference of the off-screen port, or (-1) if there is a failure.

Example:

int CChartView::OnCreate(
     LPCREATESTRUCT lpCreateStruct)
{
     if (CView::OnCreate(lpCreateStruct) == -1)
          return -1;
     HDC hDC = ::GetDC(m_hWnd);
     OGL_InitOffscreen(TRUE, hDC, 1280, 960);
     lOGLRef = OGL_RegisterOffscreenPort();
     return 0;
}

Notes:

This function can be called any number of times. After the first time, it will not have any effect and will just return the OGL Reference of the off-screen port.

Also See:

OGL_InitializeOffscreen()

OGL_RegisterPort()

 

This function creates a new OGL Reference and attaches the port (DC in Windows) to it. Memory and font objects are created, so this may take a few seconds to complete. This function returns an OGL Reference that is the internal cookie the Advanced 3D Engine uses to identify an output context. The host application must save this value because it is required to draw to the port.

Syntax:

INT32 PUBLIC
OGL_RegisterPort (
     INT32 lRef,
     HDC hPort
);

Input:

lRef: The seed reference. If an existing OGL Reference is used, the given port is attached to it (if possible). If -1 is used, a new OGL Reference is returned.

 

hPort: The platform-specific port. This port will be attached to the OGL Reference that is returned. In Windows, this is an HDC.

Return:

INT32; An OGL Reference is returned. If an existing value is used in lRef, the same value will be returned. If a new reference is created, the new value will be returned. In the case of an error, -1 will be returned.

Example:

int CChartView::OnCreate(
     LPCREATESTRUCT lpCreateStruct)
{
     if (CView::OnCreate(lpCreateStruct) == -1)
          return -1;
     HDC hDC = ::GetDC(m_hWnd);
     lOGLRef = OGL_RegisterPort(-1L, hDC);
     return 0;
}

Notes:

If an existing OGL Reference is passed in lRef and the port in hPort is incompatible, this function will fail and return (-1).

Also See:

OGL_DrawBegin, OGL_DrawEnd, OGL_RegisterOffscreenPort

OGL_SetTessellationDetail()

 

This function controls the amount of polygon detail that is used to generate the 3D objects that make up the advanced charts. Lower detail settings can drastically improve performance at the expense of visual quality.

Syntax:

void PUBLIC
OGL_SetTessellationDetail (
REAL64 fDetail
);

Input:

fDetail: A floating-point value between 0.0 and 1.0. 1.0 is the highest quality setting, 0.0 is the lowest. The default (which is in effect if this function is never called) is 1.0.

Return:

void

Notes:

If OGL_SetTessellationDetail is called before the call to OGL_RegisterPort() or OGL_RegisterOffscreenPort(), the detail value will be used to decide how complex the font models should be. After the port is registered, the font quality cannot be changed.

Also See:

OGL_RegisterPort, OGL_RegisterOffscreenPort